[{"id":23281,"web_url":"https://patchwork.libcamera.org/comment/23281/","msgid":"","date":"2022-06-01T09:07:50","subject":"Re: [libcamera-devel] [PATCH v4 12/16] Documentation: Add\n\tpython-bindings.rst","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Tomi,\n\nThank you for the patch.\n\nOn Mon, May 30, 2022 at 05:27:18PM +0300, Tomi Valkeinen wrote:\n> Add a basic doc for the Python bindings. While not really proper\n> documentation yet, the file and the examples should give enough guidance\n> for users who are somewhat familiar with libcamera.\n> \n> Signed-off-by: Tomi Valkeinen \n> ---\n> Documentation/index.rst | 1 +\n> Documentation/meson.build | 1 +\n> Documentation/python-bindings.rst | 70 +++++++++++++++++++++++++++++++\n> 3 files changed, 72 insertions(+)\n> create mode 100644 Documentation/python-bindings.rst\n> \n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 0ee10044..43d8b017 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -22,3 +22,4 @@\n> Environment variables \n> Sensor driver requirements \n> Lens driver requirements \n> + Python Bindings \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 8e2eacc6..7695bcb1 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -67,6 +67,7 @@ if sphinx.found()\n> 'guides/tracing.rst',\n> 'index.rst',\n> 'lens_driver_requirements.rst',\n> + 'python-bindings.rst',\n> 'sensor_driver_requirements.rst',\n> '../README.rst',\n> ]\n> diff --git a/Documentation/python-bindings.rst b/Documentation/python-bindings.rst\n> new file mode 100644\n> index 00000000..cfa9ec10\n> --- /dev/null\n> +++ b/Documentation/python-bindings.rst\n> @@ -0,0 +1,70 @@\n> +.. SPDX-License-Identifier: CC-BY-SA-4.0\n> +\n> +.. _python-bindings:\n> +\n> +Python Bindings for libcamera\n> +=============================\n> +\n> +*WARNING* The bindings are under work, and the API will change.\n> +\n> +Differences to the C++ API\n> +--------------------------\n> +\n> +As a rule of thumb the bindings try to follow the C++ API when possible. This\n> +chapter lists the differences.\n> +\n> +Mostly these differences fall under two categories:\n> +\n> +1. Differences caused by the inherent differences between C++ and Python.\n> +These differences are usually caused by the use of threads or differences in\n> +C++ vs Python memory management.\n> +\n> +2. Differences caused by the code being work-in-progress. It's not always\n> +trivial to create a binding in a satisfying way, and the current bindings\n> +contain simplified versions of the C++ API just to get forward. These\n> +differences are expected to eventually go away.\n> +\n> +Coding Style\n> +------------\n> +\n> +The C++ code for the bindings follows the libcamera coding style as much as\n> +possible. Note that the indentation does not quite follow the clang-format\n> +style, as clang-format makes a mess of the style used.\n> +\n> +The API visible to the Python side follows the Python style as much as possible.\n> +\n> +This means that e.g. ``Camera::generateConfiguration`` maps to\n> +``Camera.generate_configuration``.\n> +\n> +CameraManager\n> +-------------\n> +\n> +The Python API provides a singleton CameraManager via ``CameraManager.singleton()``.\n> +There is no need to start or stop the CameraManager.\n> +\n> +Handling Completed Requests\n> +---------------------------\n> +\n> +The Python bindings do not expose the ``Camera::requestCompleted`` signal\n> +directly as the signal is invoked from another thread and it has real-time\n> +constraints. Instead the bindings will internally queue the completed\n\ns/will //\n\n> +requests and use an eventfd to inform the user that there are completed\n> +requests.\n> +\n> +The user can wait on the eventfd, and upon getting an event, use\n> +``CameraManager.get_ready_requests()`` to clear the eventfd event and to get\n> +the completed requests.\n> +\n> +Controls & Properties\n> +---------------------\n> +\n> +The classes related to controls and properties are rather complex to implement\n> +directly in the Python bindings. There are some simplifications on the Python\n\ns/on /in / ?\n\n> +bindings:\n> +\n> +- There is no ControlValue class. Python objects are automatically converted\n> + to ControlValues and vice versa.\n> +- There is no ControlList class. A python dict with ControlId keys and python\n\ns/python/Python/ here ane below.\n\nReviewed-by: Laurent Pinchart \n\n> + object values is used instead.\n> +- There is no ControlInfoMap class. A python dict with ControlId keys and\n> + ControlInfo values is used instead.","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id F1E3FBD161\n\tfor ;\n\tWed, 1 Jun 2022 09:07:57 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 3F14B65635;\n\tWed, 1 Jun 2022 11:07:57 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id C7D3F633A5\n\tfor ;\n\tWed, 1 Jun 2022 11:07:55 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(lmontsouris-659-1-41-236.w92-154.abo.wanadoo.fr [92.154.76.236])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 2E44E5A4;\n\tWed, 1 Jun 2022 11:07:55 +0200 (CEST)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1654074477;\n\tbh=b6E2d5vXp3d+fcJuGl1HfbcYbIPtYJH7xClJ4fhTy3Q=;\n\th=Date:To:References:In-Reply-To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=kEBuUIFOx79AEeC7QoIP5pXHroUYM7lTj1pwFoFbNYrk0eyH3cf/DUBn9YaH2s/sE\n\tNKf3Q6c1NYRxU1KgjXTnKAeDoIzO1FeBuRwlaQUFJoy+vOdOAKF3QjWQ4cAnIRWGJ4\n\tC1sWlDjTCS8SRV38hb7V1IUgjZQm4BA9NJ3bMS5jGZLU+KzxRaL4R4n7SWXl84AM/t\n\ti/OnHOBbQKxLWTm4JsnyV5gwV50iiDQt+wu7ZOwLwEBJ7LwI/Sfi6CpxPGS2RthnEW\n\tg1gFP4GYW0R+LWtUscktCY3QxDPAieJTkoM1tX7oRmxdOwLZC6Ii/gt3dkYxa3enNG\n\tw3n0gVyeHKZqw==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1654074475;\n\tbh=b6E2d5vXp3d+fcJuGl1HfbcYbIPtYJH7xClJ4fhTy3Q=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=gH+y+DmhPTP2mWmA1UAtYzZlVNlWTuJwmfakKT6xnvR4HHbibBtzH24NOWiWG1a2X\n\tapkbJoa4/+MjU1Y109M/J+tjaVKKOaH+RUfC69NL5niCmYvAmBxX35QG6c+UB8gkzr\n\tA15sxJ8W7+LFVGL8a10dRQmW1+aENoqBRzHo4xKU="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"gH+y+Dmh\"; dkim-atps=neutral","Date":"Wed, 1 Jun 2022 12:07:50 +0300","To":"Tomi Valkeinen ","Message-ID":"","References":"<20220530142722.57618-1-tomi.valkeinen@ideasonboard.com>\n\t<20220530142722.57618-13-tomi.valkeinen@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20220530142722.57618-13-tomi.valkeinen@ideasonboard.com>","Subject":"Re: [libcamera-devel] [PATCH v4 12/16] Documentation: Add\n\tpython-bindings.rst","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Laurent Pinchart via libcamera-devel\n\t","Reply-To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]