Message ID | 20220524114610.41848-15-tomi.valkeinen@ideasonboard.com |
---|---|
State | Superseded |
Headers | show |
Series |
|
Related | show |
Hi Tomi, Thank you for the patch. On Tue, May 24, 2022 at 02:46:05PM +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> > --- > src/py/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ Should this go to Documentation/python.md ? > 1 file changed, 61 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..0a763030 > --- /dev/null > +++ b/src/py/README.md > @@ -0,0 +1,61 @@ > +# 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 Python side follows Python style as much as possible. s/to Python side/to the Python side/ s/Python style/the Python style/ > + > +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 does not expose the Camera::requestCompleted signal s/does/do/ > +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. > + You can drop this blank line. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
On 27/05/2022 10:57, Laurent Pinchart wrote: > Hi Tomi, > > Thank you for the patch. > > On Tue, May 24, 2022 at 02:46:05PM +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> >> --- >> src/py/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ > > Should this go to Documentation/python.md ? Everything there seems to be .rst, this is .md. Is that a problem? I thought Documentation/ is for the documentation that will be built into a web page/pdf. Tomi
Hi Tomi, On Fri, May 27, 2022 at 01:08:33PM +0300, Tomi Valkeinen wrote: > On 27/05/2022 10:57, Laurent Pinchart wrote: > > On Tue, May 24, 2022 at 02:46:05PM +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> > >> --- > >> src/py/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > > Should this go to Documentation/python.md ? > > Everything there seems to be .rst, this is .md. Is that a problem? > > I thought Documentation/ is for the documentation that will be built > into a web page/pdf. The Python bindings documentation isn't a second class citizen, we should eventually publish it. .rst would indeed be better to match the rest of the documentation. Would it be a big burden to convert it ?
diff --git a/src/py/README.md b/src/py/README.md new file mode 100644 index 00000000..0a763030 --- /dev/null +++ b/src/py/README.md @@ -0,0 +1,61 @@ +# 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 Python side follows 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 does 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. +
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> --- src/py/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 src/py/README.md