py: Fix include order

Python.h hence the pybind header must be included first since pyconfig.h
unconditionally overrides certain feature test macros[0]. This was mostly
hidden by the fact that macro redefinitions with the same value do not
trigger compiler warnings. However, glibc 43 has changed certain defaults[1],
causing mismatches, leading to compiler warnings.

So change the include order so that `<pybind11/...>` headers are included
first and then the local `"py_..."` headers, and then everything else. Also
remove some redundant includes.

Adjust `.clang-format` and the documentation as well.

[0]: https://docs.python.org/3/c-api/intro.html#include-files
[1]: https://sourceware.org/git/?p=glibc.git;a=commit;h=a5cc3018f31a125f019685b239c6e5a0bf1a272b

Link: https://github.com/python/cpython/issues/61322
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

.clang-format

@@ -77,6 +77,12 @@ IncludeCategories:
   - Regex:           '<Q([A-Za-z0-9\-_])+>'
     CaseSensitive:   true
     Priority:        9
+  # Python.h hence pybind11 headers must be included first
+  # https://docs.python.org/3/c-api/intro.html#include-files
+  - Regex:           '<pybind11/.*>'
+    Priority:        -9
+  - Regex:           '"py_.*"'
+    Priority:        -8
   # Headers in <> with an extension. (+system libraries)
   - Regex:           '<([A-Za-z0-9\-_])+\.h>'
     Priority:        2

Documentation/coding-style.rst

@@ -95,6 +95,12 @@ System and library headers shall be included with angle brackets. Project
 headers shall be included with angle brackets for the libcamera public API
 headers, and with double quotes for internal libcamera headers.
 
+.. note::
+   As an exception pybind11 headers and local ``py_*`` headers must be included first
+   in the Python bindings due to the requirements outlined in the `Python documentation`_.
+
+.. _Python documentation: https://docs.python.org/3/c-api/intro.html#include-files
+
 
 C++ Specific Rules
 ------------------

src/py/libcamera/py_camera_manager.cpp

@@ -4,6 +4,7 @@
  */
 
 #include "py_camera_manager.h"
+#include "py_main.h"
 
 #include <errno.h>
 #include <memory>
@@ -12,8 +13,6 @@
 #include <unistd.h>
 #include <vector>
 
-#include "py_main.h"
-
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_camera_manager.h

@@ -5,12 +5,12 @@
 
 #pragma once
 
+#include <pybind11/pybind11.h>
+
 #include <libcamera/base/mutex.h>
 
 #include <libcamera/libcamera.h>
 
-#include <pybind11/pybind11.h>
-
 using namespace libcamera;
 
 class PyCameraManager

src/py/libcamera/py_color_space.cpp

@@ -5,15 +5,14 @@
  * Python bindings - Color Space classes
  */
 
-#include <libcamera/color_space.h>
-#include <libcamera/libcamera.h>
-
 #include <pybind11/operators.h>
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
 #include "py_main.h"
 
+#include <libcamera/libcamera.h>
+
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_controls_generated.cpp.in

@@ -7,12 +7,12 @@
  * This file is auto-generated. Do not edit.
  */
 
-#include <libcamera/{{header}}>
-
 #include <pybind11/pybind11.h>
 
 #include "py_main.h"
 
+#include <libcamera/{{header}}>
+
 namespace py = pybind11;
 
 class Py{{mode|capitalize}}

src/py/libcamera/py_enums.cpp

@@ -5,12 +5,12 @@
  * Python bindings - Enumerations
  */
 
-#include <libcamera/libcamera.h>
-
 #include <pybind11/pybind11.h>
 
 #include "py_main.h"
 
+#include <libcamera/libcamera.h>
+
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_formats_generated.cpp.in

@@ -7,12 +7,12 @@
  * This file is auto-generated. Do not edit.
  */
 
-#include <libcamera/formats.h>
-
 #include <pybind11/pybind11.h>
 
 #include "py_main.h"
 
+#include <libcamera/formats.h>
+
 namespace py = pybind11;
 
 class PyFormats

src/py/libcamera/py_geometry.cpp

@@ -5,17 +5,16 @@
  * Python bindings - Geometry classes
  */
 
-#include <array>
-
-#include <libcamera/geometry.h>
-#include <libcamera/libcamera.h>
-
 #include <pybind11/operators.h>
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
 #include "py_main.h"
 
+#include <array>
+
+#include <libcamera/libcamera.h>
+
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_helpers.cpp

@@ -3,14 +3,14 @@
  * Copyright (C) 2022, Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
  */
 
-#include "py_helpers.h"
-
-#include <libcamera/libcamera.h>
-
 #include <pybind11/functional.h>
 #include <pybind11/stl.h>
 #include <pybind11/stl_bind.h>
 
+#include "py_helpers.h"
+
+#include <libcamera/libcamera.h>
+
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_helpers.h

@@ -5,9 +5,9 @@
 
 #pragma once
 
-#include <libcamera/libcamera.h>
-
 #include <pybind11/pybind11.h>
 
+#include <libcamera/libcamera.h>
+
 pybind11::object controlValueToPy(const libcamera::ControlValue &cv);
 libcamera::ControlValue pyToControlValue(const pybind11::object &ob, libcamera::ControlType type);

src/py/libcamera/py_main.cpp

@@ -5,6 +5,13 @@
  * Python bindings
  */
 
+#include <pybind11/functional.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <pybind11/stl_bind.h>
+
+#include "py_camera_manager.h"
+#include "py_helpers.h"
 #include "py_main.h"
 
 #include <limits>
@@ -17,14 +24,6 @@
 
 #include <libcamera/libcamera.h>
 
-#include <pybind11/functional.h>
-#include <pybind11/pybind11.h>
-#include <pybind11/stl.h>
-#include <pybind11/stl_bind.h>
-
-#include "py_camera_manager.h"
-#include "py_helpers.h"
-
 namespace py = pybind11;
 
 using namespace libcamera;

src/py/libcamera/py_main.h

@@ -5,10 +5,10 @@
 
 #pragma once
 
-#include <libcamera/base/log.h>
-
 #include <pybind11/pybind11.h>
 
+#include <libcamera/base/log.h>
+
 namespace libcamera {
 
 LOG_DECLARE_CATEGORY(Python)

src/py/libcamera/py_transform.cpp

@@ -5,15 +5,14 @@
  * Python bindings - Transform class
  */
 
-#include <libcamera/transform.h>
-#include <libcamera/libcamera.h>
-
 #include <pybind11/operators.h>
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
 #include "py_main.h"
 
+#include <libcamera/libcamera.h>
+
 namespace py = pybind11;
 
 using namespace libcamera;