[libcamera-devel,v3,11/30] py: Add README.md
diff mbox series

Message ID 20220527144447.94891-12-tomi.valkeinen@ideasonboard.com
State Superseded
Headers show
Series
  • More misc Python patches
Related show

Commit Message

Tomi Valkeinen May 27, 2022, 2:44 p.m. UTC
Add a basic README for the Python bindings. While not a proper doc, the
README 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>
---
 src/py/README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 src/py/README.md

Comments

Laurent Pinchart May 30, 2022, 9:30 a.m. UTC | #1
Hi Tomi,

Thank you for the patch.

On Fri, May 27, 2022 at 05:44:28PM +0300, Tomi Valkeinen wrote:
> Add a basic README for the Python bindings. While not a proper doc, the
> README 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>
> ---
>  src/py/README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++

As discussed in the review of v2, would it be much work to convert this
to .rst and move it to Documentation/ ?

>  1 file changed, 60 insertions(+)
>  create mode 100644 src/py/README.md
> 
> diff --git a/src/py/README.md b/src/py/README.md
> new file mode 100644
> index 00000000..74a8cd9f
> --- /dev/null
> +++ b/src/py/README.md
> @@ -0,0 +1,60 @@
> +# 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 will internally queue the completed
> +requests 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.read_event() to clear the eventfd event and
> +CameraManager.get_ready_requests() 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 on 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.
Tomi Valkeinen May 30, 2022, 9:46 a.m. UTC | #2
On 30/05/2022 12:30, Laurent Pinchart wrote:
> Hi Tomi,
> 
> Thank you for the patch.
> 
> On Fri, May 27, 2022 at 05:44:28PM +0300, Tomi Valkeinen wrote:
>> Add a basic README for the Python bindings. While not a proper doc, the
>> README 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>
>> ---
>>   src/py/README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
> 
> As discussed in the review of v2, would it be much work to convert this
> to .rst and move it to Documentation/ ?

Yes, I've done that for v4.

  Tomi

Patch
diff mbox series

diff --git a/src/py/README.md b/src/py/README.md
new file mode 100644
index 00000000..74a8cd9f
--- /dev/null
+++ b/src/py/README.md
@@ -0,0 +1,60 @@ 
+# 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 will internally queue the completed
+requests 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.read_event() to clear the eventfd event and
+CameraManager.get_ready_requests() 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 on 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.