[CMake] Add black formatter for Python files

and enable checking it in CI.

Author: lukaszstolarczuk

.github/workflows/pr_push.yml

@@ -94,7 +94,7 @@ jobs:
     - name: Install apt packages
       run: |
         sudo apt-get update
-        sudo apt-get install -y cmake clang-format-15 cmake-format libhwloc-dev
+        sudo apt-get install -y black cmake clang-format-15 cmake-format libhwloc-dev
 
     - name: Configure CMake
       run: >
@@ -112,6 +112,9 @@ jobs:
     - name: Check cmake-format
       run: cmake --build build --target cmake-format-check
 
+    - name: Check Python formatting
+      run: cmake --build build --target black-format-check
+
   DocsBuild:
     name: Build docs
     runs-on: ubuntu-latest

CMakeLists.txt

@@ -25,7 +25,10 @@ option(UMF_BUILD_EXAMPLES "Build UMF examples" ON)
 option(UMF_ENABLE_POOL_TRACKING "Build UMF with pool tracking" ON)
 option(UMF_DEVELOPER_MODE "Enable developer checks, treats warnings as errors"
        OFF)
-option(UMF_FORMAT_CODE_STYLE "Format UMF code with clang-format" OFF)
+option(
+    UMF_FORMAT_CODE_STYLE
+    "Add clang, cmake, and black -format-check and -format-apply targets to make"
+    OFF)
 option(USE_ASAN "Enable AddressSanitizer checks" OFF)
 option(USE_UBSAN "Enable UndefinedBehaviorSanitizer checks" OFF)
 option(USE_TSAN "Enable ThreadSanitizer checks" OFF)
@@ -255,13 +258,16 @@ if(UMF_FORMAT_CODE_STYLE)
     find_program(CLANG_FORMAT NAMES clang-format-15 clang-format-15.0
                                     clang-format)
     find_program(CMAKE_FORMAT NAMES cmake-format)
+    find_program(BLACK NAMES black)
 
-    if(NOT CLANG_FORMAT AND NOT CMAKE_FORMAT)
+    if(NOT CLANG_FORMAT
+       AND NOT CMAKE_FORMAT
+       AND NOT BLACK)
         message(
             FATAL_ERROR
                 "UMF_FORMAT_CODE_STYLE=ON, but neither clang-format (required version: "
-                "${CLANG_FORMAT_REQUIRED}) nor cmake-format (required version: "
-                "${CMAKE_FORMAT_VERSION}) was found.")
+                "${CLANG_FORMAT_REQUIRED}), nor cmake-format (required version: "
+                "${CMAKE_FORMAT_VERSION}), nor black was found.")
     endif()
 
     if(CLANG_FORMAT)
@@ -365,24 +371,52 @@ if(UMF_FORMAT_CODE_STYLE)
             COMMENT "Format Cmake files using cmake-format")
     endif()
 
-    # Add a convenience target for running both tools at once - available only
-    # if both are found.
-    if(CLANG_FORMAT AND CMAKE_FORMAT)
+    if(BLACK)
+        # black should maintain backward compatibility, we don't have to require
+        # a specific version
+        get_program_version_major_minor(${BLACK} BLACK_VERSION)
+        message(STATUS "Found black: ${BLACK} (version: ${BLACK_VERSION})")
+
+        message(
+            STATUS
+                "Adding 'black-format-check' and 'black-format-apply' make targets"
+        )
+
+        add_custom_target(
+            black-format-check
+            COMMAND ${BLACK} --check --verbose ${CMAKE_SOURCE_DIR}
+            COMMENT "Check Python files formatting using black formatter")
+
+        add_custom_target(
+            black-format-apply
+            COMMAND ${BLACK} ${CMAKE_SOURCE_DIR}
+            COMMENT "Format Python files using black formatter")
+    endif()
+
+    # Add a convenience target for running all tools at once - available only if
+    # all are found.
+    if(CLANG_FORMAT
+       AND CMAKE_FORMAT
+       AND BLACK)
         add_custom_target(
             format-check
             COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
                     clang-format-check
             COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
                     cmake-format-check
-            COMMENT "Running both clang-format-check and cmake-format-check")
+            COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
+                    black-format-check
+            COMMENT "Running all formatting checks")
 
         add_custom_target(
             format-apply
             COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
                     clang-format-apply
             COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
                     cmake-format-apply
-            COMMENT "Format files using clang-format and cmake-format")
+            COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target
+                    black-format-apply
+            COMMENT "Format C/C++, CMake, and Python files")
     else()
         message(
             STATUS

CONTRIBUTING.md

@@ -62,10 +62,11 @@ To enable additional checks (including `-Werror` / `/WX` compilation flag), swit
 ["CMake standard options"](./README.md#cmake-standard-options) section in the top-level Readme.
 
 ### Code style
-We use `clang-format` to verify and apply code style changes to source files. 
+We use `clang-format` to verify and apply code style changes to C/C++ source files.
 To see all rules we require, please take a look at `.clang-format` file in the 
 root directory of this repository. Similarly, we use `cmake-format` tool and
 `.cmake-format` file to verify and apply code style changes to CMake files.
+For Python source files we use `black` tool.
 
 To enable code style checks and re-formatting, CMake option `UMF_FORMAT_CODE_STYLE` has to
 be switched on. You'll then have additional CMake targets available.
@@ -74,7 +75,7 @@ To verify correct coding style of your changes execute (assuming `build` is your
 
 ```bash
 $ cmake -B build -DUMF_FORMAT_CODE_STYLE=ON
-$ cmake --build build --target format-checks
+$ cmake --build build --target format-check
 ```
 
 We run these checks in our Continuous Integration (CI). So, if any issues were found,
@@ -87,9 +88,10 @@ $ cmake --build build --target format-apply
 # Remember to review introduced changes
 ```
 
-If you wish to use only `clang-format` or only `cmake-format`, you can execute the corresponding
-`clang-format-check` and `clang-format-apply` for source files, or `cmake-format-check` and
-`cmake-format-apply` for CMake files, respectively.
+If you wish to use only `clang-format`, or `cmake-format`, or `black`, you can execute the corresponding
+`clang-format-check` and `clang-format-apply` for C/C++ source files, or `cmake-format-check` and
+`cmake-format-apply` for CMake files, or `black-format-check` and `black-format-apply` for Python
+source files, respectively.
 
 **NOTE**: We use specific versions of formatting tools to ensure consistency across the project. The required versions are:
 - clang-format version **15.0**, which can be installed with the command: `python -m pip install clang-format==15.0.7`.

README.md

@@ -102,7 +102,7 @@ List of options provided by CMake:
 | UMF_BUILD_EXAMPLES | Build UMF examples | ON/OFF | ON |
 | UMF_ENABLE_POOL_TRACKING | Build UMF with pool tracking | ON/OFF | ON |
 | UMF_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
-| UMF_FORMAT_CODE_STYLE | Add clang and cmake -format-check and -format-apply targets to make | ON/OFF | OFF |
+| UMF_FORMAT_CODE_STYLE | Add clang, cmake, and black -format-check and -format-apply targets to make | ON/OFF | OFF |
 | USE_ASAN | Enable AddressSanitizer checks | ON/OFF | OFF |
 | USE_UBSAN | Enable UndefinedBehaviorSanitizer checks | ON/OFF | OFF |
 | USE_TSAN | Enable ThreadSanitizer checks | ON/OFF | OFF |

third_party/requirements.txt

@@ -2,6 +2,7 @@
 # Formatting the source code
 clang-format==15.0.7
 cmake-format==0.6.13
+black==23.7.0
 # Generating HTML documentation
 pygments==2.15.1
 sphinxcontrib_applehelp==1.0.4