COMP: Enhance Python wrapping logic and configuration

hjmjohnson · hjmjohnson · commit c385b1b7c846 · 2025-11-07T11:03:05.000-06:00
- Refactored Python LIMITED_API setup for improved modularity and reusability.
- Adjusted `itk_end_wrap_module.cmake` to properly handle LIMITED_API settings.
- Updated `ITKSetPython3Vars.cmake` to streamline Python version selection and configuration.
- Introduced logic to infer `Python3_ROOT_DIR` when `Python3_EXECUTABLE` is specified.
- Improved maintainability by centralizing Python-related configuration and ensuring consistency across CMake files.
- Fix linking of ITKCommon when including python support
diff --git a/CMake/ITKSetPython3Vars.cmake b/CMake/ITKSetPython3Vars.cmake
@@ -6,93 +6,120 @@
 # Additionally, setting Python3_EXECUTABLE can be used to set the Python version explicitly, but
 # may become less reliable with newer versions of CMake (as opposed setting FindPython3 HINTS).  Current
 # implementation gives preference to active virtualenvs.
-
 cmake_policy(SET CMP0094 NEW) # makes FindPython3 prefer activated virtualenv Python to latest version
 set(PYTHON_VERSION_MIN 3.9)
 set(PYTHON_VERSION_MAX 3.999)
-if(MSVC AND CMAKE_BUILD_TYPE STREQUAL "Debug")
-  set(
-    Python3_FIND_ABI
-    "OFF" # pydebug - use non-debug python even for debug builds
-    "ANY" # pymalloc
-    "ANY" # unicode
-    "ANY" # gil_disabled
+
+if(NOT PYTHON_DEVELOPMENT_REQUIRED)
+  # if not PYTHON_DEVELOPMENT_REQUIRED, just find some version of
+  # Python (don't need to be as specific)
+  find_package(
+    Python3
+    ${PYTHON_VERSION_MIN}...${PYTHON_VERSION_MAX}
+    COMPONENTS
+      Interpreter
   )
 else()
   set(
     Python3_FIND_ABI
-    "OFF" # pydebug
+    "OFF" # pydebug - use non-debug python even for debug builds
     "ANY" # pymalloc
     "ANY" # unicode
-    "ANY" # gil_disabled
   )
-endif()
+  # For CMake >= 3.30, append an additional ANY to Python3_FIND_ABI to
+  # accommodate newer FindPython3 ABI fields (e.g., free-threaded builds).
+  if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.30")
+    list(APPEND Python3_FIND_ABI "ANY") # gil_disabled
+  endif()
 
-if(PYTHON_DEVELOPMENT_REQUIRED)
   if(DEFINED Python3_EXECUTABLE) # if already specified
     set(_specified_Python3_EXECUTABLE ${Python3_EXECUTABLE})
   endif()
   # set(Python3_FIND_REGISTRY LAST) # default is FIRST. Do we need/want this?
   find_package(
+    # Used to find the exact version for setting ITK_WRAP_PYTHON_VERSION
+    # NOTE: no REQUIRED FLAG during this call to find_package, just search
+    #       for a best fit version to support wrapping
     Python3
     ${PYTHON_VERSION_MIN}...${PYTHON_VERSION_MAX}
     COMPONENTS
       Interpreter
+      Development
       Development.Module
-      ${SKBUILD_SABI_COMPONENT}
-      NumPy # Required for ITK, prefer to fail early
+      Development.SABIModule
+      NumPy
   )
+  if(ITK_WRAP_PYTHON)
+    set(ITK_WRAP_PYTHON_VERSION "${Python3_VERSION}")
+  else()
+    set(ITK_WRAP_PYTHON_VERSION "ITK_WRAP_PYTHON=OFF")
+  endif()
+
   # start section to define package components based on LIMITED_API support and choices
   set(_ITK_MINIMUM_SUPPORTED_LIMITED_API_VERSION 3.11)
-  if(
-    ITK_WRAP_PYTHON_VERSION
-      VERSION_GREATER_EQUAL
-      ${_ITK_MINIMUM_SUPPORTED_LIMITED_API_VERSION}
+
+  # Force ITK_WRAP_PYTHON_VERSION if SKBUILD_SABI_COMPONENT requests it
+  string(
+    FIND
+    "${SKBUILD_SABI_COMPONENT}"
+    "${SABIModule}"
+    _SKBUILD_SABI_COMPONENT_REQUIRED
   )
+  if(NOT DEFINED ITK_USE_PYTHON_LIMITED_API)
+    if(
+      (
+        _SKBUILD_SABI_COMPONENT_REQUIRED
+          GREATER
+          -1
+      )
+      OR
+        ITK_WRAP_PYTHON_VERSION
+          VERSION_GREATER_EQUAL
+          ${_ITK_MINIMUM_SUPPORTED_LIMITED_API_VERSION}
+    )
+      set(
+        ITK_USE_PYTHON_LIMITED_API
+        1
+        CACHE BOOL
+        "Configure Python's limited API for Python minor version compatibility."
+      )
+    else()
+      set(
+        ITK_USE_PYTHON_LIMITED_API
+        0
+        CACHE BOOL
+        "Configure Python's limited API for Python minor version compatibility."
+      )
+    endif()
+    mark_as_advanced(ITK_USE_PYTHON_LIMITED_API)
+  endif()
+  unset(_SKBUILD_SABI_COMPONENT_REQUIRED)
+  if(ITK_USE_PYTHON_LIMITED_API)
     set(
-      ITK_USE_PYTHON_LIMITED_API
-      1
-      CACHE BOOL
-      "Configure Python's limited API for Python minor version compatibility."
+      _python_find_components
+      Interpreter
+      Development
+      Development.SABIModule
+      NumPy # NumPy Required for ITK, prefer to fail early
     )
   else()
     set(
-      ITK_USE_PYTHON_LIMITED_API
-      0
-      CACHE BOOL
-      "Configure Python's limited API for Python minor version compatibility."
+      _python_find_components
+      Interpreter
+      Development
+      Development.Module
+      NumPy # NumPy Required for ITK, prefer to fail early
     )
   endif()
-  mark_as_advanced(ITK_USE_PYTHON_LIMITED_API)
 
-  set(_development_component "Development.Module")
-  set(_Python3_ABI_SETTINGS)
-  if(ITK_USE_PYTHON_LIMITED_API)
-    set(_development_component "Development.SABIModule")
-    set(
-      _Python3_ABI_SETTINGS
-      USE_SABI
-      ${_ITK_MINIMUM_SUPPORTED_LIMITED_API_VERSION}
-      WITH_SOABI
-    )
-  endif()
-  set(
-    _py_components
-    Interpreter
-    ${_development_component}
-    NumPy # Required for ITK, prefer to fail early
-    ${SKBUILD_SABI_COMPONENT}
-  )
-  list(REMOVE_DUPLICATES _py_components)
   find_package(
     Python3
     ${ITK_WRAP_PYTHON_VERSION} # Force python version to match previously found
     REQUIRED
     COMPONENTS
-      ${_py_components}
+      ${_python_find_components}
   )
-  unset(_py_components)
-  unset(_development_component)
+  unset(_python_find_components)
   unset(_ITK_MINIMUM_SUPPORTED_LIMITED_API_VERSION)
   # end section to define package components based on LIMITED_API support and choices
   if(DEFINED _specified_Python3_EXECUTABLE)
@@ -104,35 +131,81 @@ if(PYTHON_DEVELOPMENT_REQUIRED)
       FORCE
     )
   endif()
-else() # if not PYTHON_DEVELOPMENT_REQUIRED, just find some version of Python (don't need to be as specific)
-  find_package(
-    Python3
-    ${PYTHON_VERSION_MIN}...${PYTHON_VERSION_MAX}
-    COMPONENTS
-      Interpreter
-  )
-endif()
-if(ITK_WRAP_PYTHON)
-  set(ITK_WRAP_PYTHON_VERSION "${Python3_VERSION}")
-else()
-  set(ITK_WRAP_PYTHON_VERSION "ITK_WRAP_PYTHON=OFF")
-endif()
-if(NOT Python3_EXECUTABLE AND _specified_Python3_EXECUTABLE) # workaround for cases where FindPython3 fails to set correctly
-  set(
-    Python3_EXECUTABLE
-    ${_specified_Python3_EXECUTABLE}
-    CACHE INTERNAL
-    "Path to the Python interpreter"
-    FORCE
+
+  if(NOT Python3_EXECUTABLE AND _specified_Python3_EXECUTABLE) # workaround for cases where FindPython3 fails to set correctly
+    set(
+      Python3_EXECUTABLE
+      ${_specified_Python3_EXECUTABLE}
+      CACHE INTERNAL
+      "Path to the Python interpreter"
+      FORCE
+    )
+  endif()
+
+  # If a specific Python3_EXECUTABLE is provided by the user, try to infer
+  # the corresponding Python3_ROOT_DIR for Unix/macOS/Linux so CMake's
+  # FindPython3 locates the matching installation or virtual environment.
+  # This is especially important for virtualenv/venv/conda environments.
+  if(
+    DEFINED
+      Python3_EXECUTABLE
+    AND
+      NOT
+        DEFINED
+          Python3_ROOT_DIR
+    AND
+      (
+        UNIX
+        OR
+          APPLE
+      )
+    AND
+      NOT
+        WIN32
   )
-endif()
+    # First, try sys.prefix from the provided interpreter (works for venv/conda)
+    execute_process(
+      COMMAND
+        "${Python3_EXECUTABLE}" -c "import sys; print(sys.prefix)"
+      OUTPUT_VARIABLE _py_prefix
+      ERROR_VARIABLE _py_prefix_err
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    if(_py_prefix)
+      file(TO_CMAKE_PATH "${_py_prefix}" _py_root_hint)
+    endif()
 
-# Add user-visible cache entry
-set(
-  Python3_ROOT_DIR
-  ${Python3_ROOT_DIR}
-  CACHE PATH
-  "Which installation or virtual environment of Python to use"
-  FORCE
-)
-mark_as_advanced(Python3_ROOT_DIR)
+    # Fallback: parent of the interpreter's bin directory, e.g., /path/to/env
+    # from /path/to/env/bin/python3
+    if(NOT _py_root_hint)
+      get_filename_component(_py_exe_dir "${Python3_EXECUTABLE}" DIRECTORY)
+      get_filename_component(_py_root_hint "${_py_exe_dir}/.." REALPATH)
+    endif()
+
+    if(_py_root_hint)
+      set(
+        Python3_ROOT_DIR
+        "${_py_root_hint}"
+        CACHE PATH
+        "Which installation or virtual environment of Python to use"
+        FORCE
+      )
+      mark_as_advanced(Python3_ROOT_DIR)
+    endif()
+    unset(_py_prefix)
+    unset(_py_prefix_err)
+    unset(_py_exe_dir)
+    unset(_py_root_hint)
+  endif()
+  if(Python3_ROOT_DIR)
+    # Add user-visible cache entry if Python3_ROOT_DIR value is set
+    set(
+      Python3_ROOT_DIR
+      ${Python3_ROOT_DIR}
+      CACHE PATH
+      "Which installation or virtual environment of Python to use"
+      FORCE
+    )
+    mark_as_advanced(Python3_ROOT_DIR)
+  endif()
+endif()
diff --git a/Modules/Core/Common/src/CMakeLists.txt b/Modules/Core/Common/src/CMakeLists.txt
@@ -254,6 +254,13 @@ if(UNIX)
     target_link_libraries(ITKCommon LINK_PUBLIC ${CMAKE_DL_LIBS})
   endif()
 endif()
+if(ITK_WRAP_PYTHON)
+  if(ITK_USE_PYTHON_LIMITED_API)
+    target_link_libraries(ITKCommon PRIVATE Python3::SABIModule)
+  else()
+    target_link_libraries(ITKCommon PRIVATE Python3::Module)
+  endif()
+endif()
 
 if(ITK_USE_TBB)
   # https://software.intel.com/en-us/node/506139
diff --git a/Wrapping/macro_files/itk_end_wrap_module.cmake b/Wrapping/macro_files/itk_end_wrap_module.cmake
@@ -483,6 +483,16 @@ ${DO_NOT_WAIT_FOR_THREADS_CALLS}
   # build all the c++ files from this module in a common lib
   if(NOT TARGET ${lib})
     # -- START PYTHON MODULE CREATION
+    if(ITK_USE_PYTHON_LIMITED_API)
+      set(
+        _Python3_ABI_SETTINGS
+        USE_SABI
+        ${Python3_VERSION_MAJOR}.${Python3_VERSION_MINOR}
+        WITH_SOABI
+      )
+    else()
+      unset(_Python3_ABI_SETTINGS)
+    endif()
 
     #Python3_add_library sets PREFIX "" and the correct extension suffix automatically.
     # No manual SUFFIX editing is needed.
