[PyOV] Initial support for type hinting using stub .pyi files (#29139)

### Turning on type hinting in VSC:
 - Install Python and Pylance extensions
- Turn on type checking as described in
https://docs.pydantic.dev/latest/integrations/visual_studio_code/#configure-pylance
 - The stubs should show hints for OpenVINO API:

![image](https://github.com/user-attachments/assets/f211ef90-ccf0-4bd0-a553-f31483ad7950)

### Details:
 - Work in progress, **draft is for internal Python team review only**
 - Fix or skip errors thrown during stub generation
- Fix some of the errors thrown by `pylance` when reading .pyi files
(there's quite a few of them, in my opinion the rest has to be fixed
separately in different PRs)
- Adjust CMake scripts for wheel building dependencies and for fdupes
check
 - Add script with xfails, which will be used for stub generation
- This PR is called "initial support" due to numerous leftover errors
reported by `pylance`, such as:

![image](https://github.com/user-attachments/assets/7c8d0740-cfe3-45d4-b564-ed93489a8a0d)
In my opinion the rest should be fixed systematically and in scope of
other PRs, mostly due to variety of errors, which often require case by
case analysis.

### TBD:
- ~~The workflow for updating stubs has to be decided on. In current
implementation, the stubs need to be generated manually and committed.
They are also stored in the repository. Maybe they should be generated
just before wheel building (automatically) and not uploaded to GitHub?~~
**The current plan is to automatically generate and commit `.pyi` files
using pre-commit git hook.**
- ~~If we decide to keep `.pyi` files like GenAI does, we'll need a CI
check to assert that they're up to date, similar to GenAI:
openvinotoolkit/openvino.genai#1214 - **will
be continued in an epic specific to PyAPI stubs introduction**
- ~~Should the `generate_pyapi_stubs.sh` script be in
`openvino/scripts`?~~ **Moved to Python directory**
- ~~Is the current implementation sufficient for initial support or
should we first go through the modules and fix all the `pylance`
errors?~~

### To do:
 - Verify the `.bat` script is working correctly

### Tickets:
 - CVS-157373

---------

Signed-off-by: p-wysocki <[email protected]>
Co-authored-by: Anastasia Kuporosova <[email protected]>

Author: p-wysocki

.gitignore

@@ -3,9 +3,11 @@ _*
 [Bb]uild*/
 cmake-build*
 
-# but ensure we don't skip __init__.py and __main__.py
+# but ensure we don't skip Python files
 !__init__.py
 !__main__.py
+!*.pyi
+
 # and sphinx documentation folders
 !docs/sphinx_setup/_*
 

src/bindings/python/CMakeLists.txt

@@ -271,6 +271,8 @@ macro(ov_define_setup_py_dependencies)
     endforeach()
 
     file(GLOB_RECURSE openvino_py_files ${OpenVINOPython_SOURCE_DIR}/src/openvino/*.py)
+    file(GLOB_RECURSE openvino_pyi_files ${OpenVINOPython_SOURCE_DIR}/src/openvino/*.pyi)
+    list(APPEND openvino_py_files ${openvino_pyi_files})
 
     list(APPEND ov_setup_py_deps
         ${openvino_py_files}
@@ -411,3 +413,36 @@ if(OpenVINODeveloperPackage_FOUND)
 
     ov_cpack(${OV_CPACK_COMPONENTS_ALL})
 endif()
+
+# only for developers, skip on CI
+if(NOT DEFINED ENV{CI_BUILD_DEV_TAG} AND NOT DEFINED CI_BUILD_NUMBER)
+
+    # check pybind11-stubgen package
+    execute_process(COMMAND ${Python3_EXECUTABLE} -m pip show pybind11-stubgen
+                    OUTPUT_VARIABLE pybind11_stubgen_info OUTPUT_STRIP_TRAILING_WHITESPACE
+                    RESULT_VARIABLE pybind11_stubgen_result)
+    string(REGEX MATCH "Version: ([\\.0-9]+)" pybind11_stubgen_version "${pybind11_stubgen_info}")
+    if(pybind11_stubgen_result OR NOT pybind11_stubgen_version)
+        message(FATAL_ERROR "pybind11-stubgen package is not installed or version is not detected. This package is necessary for developing Python API.")
+    endif()
+
+    # check pre-commit package    
+    execute_process(COMMAND ${Python3_EXECUTABLE} -m pip show pre-commit
+                    OUTPUT_VARIABLE precommit_pkg_info OUTPUT_STRIP_TRAILING_WHITESPACE
+                    RESULT_VARIABLE precommit_pkg_result)
+    string(REGEX MATCH "Version: ([\\.0-9]+)" precommit_pkg_version "${precommit_pkg_info}")
+    if(precommit_pkg_result OR NOT precommit_pkg_version)
+        message(FATAL_ERROR "pre-commit package is not installed or version is not detected. This package is necessary for developing Python API.")
+    endif()
+
+    # attach the pre-commit hook for Python stub generation
+    execute_process(COMMAND pre-commit install -c "${CMAKE_CURRENT_SOURCE_DIR}/scripts/stub_generation_precommit.yaml"
+                    RESULT_VARIABLE precommit_install_result
+                    ERROR_VARIABLE precommit_install_error
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    ERROR_STRIP_TRAILING_WHITESPACE)
+    if(NOT precommit_install_result EQUAL "0")
+        message(FATAL_ERROR "pre-commit hook install failed with error: ${precommit_install_error}")
+    endif()
+    message(STATUS "pre-commit hook for Python API stub generation has been installed")
+endif()

src/bindings/python/requirements_test.txt

@@ -36,3 +36,5 @@ retrying
 tox
 types-setuptools
 wheel
+pybind11-stubgen<2.6
+pre-commit<4.3

src/bindings/python/scripts/generate_pyapi_stubs.bat

@@ -0,0 +1,126 @@
+@echo off
+
+REM Copyright (C) 2018-2025 Intel Corporation
+REM SPDX-License-Identifier: Apache-2.0
+
+setlocal EnableDelayedExpansion
+
+REM Invalid expressions
+set "invalid_expressions=ov::op::v1::Add ov::op::v1::Divide ov::op::v1::Multiply ov::op::v1::Subtract ov::op::v1::Divide ov::Node ov::Input<ov::Node> ov::descriptor::Tensor <Type: 'undefined'> ov::Output<ov::Node const> ov::float16 ov::EncryptionCallbacks ov::streams::Num <Dimension: dynamic ov::pass::pattern::PatternSymbolValue <RTMap>"
+
+REM Invalid identifiers
+set "invalid_identifiers=<locals>"
+
+REM Unresolved names
+set "unresolved_names=InferRequestWrapper RemoteTensorWrapper capsule VASurfaceTensorWrapper _abc._abc_data openvino._ov_api.undefined_deprecated  InputCutInfo ParamData"
+
+REM Function to escape characters for regex
+:escape_characters
+set "escaped_error=%~1"
+set "escaped_error=!escaped_error:\=\\!"
+set "escaped_error=!escaped_error:/=\/!"
+set "escaped_error=!escaped_error:$=\$!"
+set "escaped_error=!escaped_error:*=\*!"
+set "escaped_error=!escaped_error:.=\.!"
+set "escaped_error=!escaped_error:^=\^!"
+set "escaped_error=!escaped_error:|=\|!"
+exit /b 0
+
+REM Create regex pattern
+set "invalid_expressions_regex="
+for %%e in (%invalid_expressions%) do (
+    call :escape_characters "%%e"
+    set "invalid_expressions_regex=!invalid_expressions_regex!.*!escaped_error!.*|"
+)
+set "invalid_expressions_regex=%invalid_expressions_regex:~0,-1%"
+
+set "invalid_identifiers_regex="
+for %%e in (%invalid_identifiers%) do (
+    call :escape_characters "%%e"
+    set "invalid_identifiers_regex=!invalid_identifiers_regex!.*!escaped_error!.*|"
+)
+set "invalid_identifiers_regex=%invalid_identifiers_regex:~0,-1%"
+
+set "unresolved_names_regex="
+for %%e in (%unresolved_names%) do (
+    call :escape_characters "%%e"
+    set "unresolved_names_regex=!unresolved_names_regex!.*!escaped_error!.*|"
+)
+set "unresolved_names_regex=%unresolved_names_regex:~0,-1%"
+
+REM Set the output directory
+if "%~1"=="" (
+    set "output_dir=%~dp0.."
+) else (
+    set "output_dir=%~1"
+)
+
+REM Generate stubs for C++ bindings
+python -m pybind11_stubgen --output-dir "%output_dir%" --root-suffix "" --ignore-invalid-expressions "%invalid_expressions_regex%" --ignore-invalid-identifiers "%invalid_identifiers_regex%" --ignore-unresolved-names "%unresolved_names_regex%" --print-invalid-expressions-as-is --numpy-array-use-type-var --exit-code openvino
+
+REM Check if the command was successful
+if %errorlevel% neq 0 (
+    echo Error: pybind11-stubgen failed.
+    exit /b 1
+)
+
+REM Check if the stubs were actually generated
+if exist "%output_dir%\openvino" (
+    echo Stub files generated successfully.
+) else (
+    echo No stub files were generated.
+    exit /b 1
+)
+
+REM Workaround for pybind11-stubgen issue where it doesn't import some modules for stubs generated from .py files
+REM Ticket: 163225
+set "pyi_file=%output_dir%\openvino\_ov_api.pyi"
+if exist "%pyi_file%" (
+    powershell -Command "(gc '%pyi_file%') -replace '(^.*$)', 'import typing`r`nimport pathlib`r`n$1' | Out-File -encoding ASCII '%pyi_file%'"
+) else (
+    echo File %pyi_file% not found.
+    exit /b 1
+)
+
+REM Find all changed .pyi files
+for /f "tokens=*" %%f in ('git diff --name-only ^| findstr /r "\.pyi$"') do (
+    REM Process each changed .pyi file
+    powershell -Command "(gc '%%f') -replace '<function _get_node_factory at 0x[0-9a-fA-F]+>', '<function _get_node_factory at memory_address>' | Out-File -encoding ASCII '%%f'"
+    powershell -Command "(gc '%%f') -replace '__version__: str = ''[^'']*''', '__version__: str = ''version_string''' | Out-File -encoding ASCII '%%f'"
+    powershell -Command "(gc '%%f') -replace '<function <lambda> at 0x[0-9a-fA-F]+>', '<function <lambda> at memory_address>' | Out-File -encoding ASCII '%%f'"
+    powershell -Command "(gc '%%f') -replace ': \.\.\.', ': typing.Any' | Out-File -encoding ASCII '%%f'"
+    powershell -Command "(gc '%%f') -replace 'pass: MatcherPass', 'matcher_pass: MatcherPass' | Out-File -encoding ASCII '%%f'"
+    REM Sort consecutive import statements at the beginning of the file
+    powershell -Command @"
+    \$content = Get-Content '%%f'
+    \$in_imports = \$false
+    \$start = 0
+    \$imports = @()
+
+    foreach (\$line in \$content) {
+        if (\$line -match '^from ' -or \$line -match '^import ') {
+            if (-not \$in_imports) {
+                \$start = \$true
+            }
+            \$in_imports = \$true
+            \$imports += \$line
+        } else {
+            if (\$in_imports) {
+                \$imports = \$imports | Sort-Object
+                \$imports | Out-File -Append -Encoding ASCII '%%f'
+                \$in_imports = \$false
+                \$imports = @()
+            }
+            Add-Content -Path '%%f' -Value \$line
+        }
+    }
+
+    if (\$in_imports) {
+        \$imports = \$imports | Sort-Object
+        \$imports | Out-File -Append -Encoding ASCII '%%f'
+    }
+    Add-Content -Path '%%f' -Value '# type: ignore'
+"@
+)
+
+endlocal

src/bindings/python/scripts/generate_pyapi_stubs.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+
+# Copyright (C) 2018-2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+# When removing xfails remember to remove them from .bat script as well
+invalid_expressions=(
+    # The classes bindings' will be soon added to pyopenvino. Ticket: 163077
+    "ov::op::v1::Add"
+    "ov::op::v1::Divide"
+    "ov::op::v1::Multiply"
+    "ov::op::v1::Subtract"
+    "ov::op::v1::Divide"
+
+    # Circular dependency Input/Output/Node/Tensor. Ticket: 163078
+    "ov::Node"
+    "ov::Input<ov::Node>"
+    "ov::descriptor::Tensor"
+    "<Type: 'undefined'>"
+    "ov::Output<ov::Node const>"
+
+    # New bindings required, ticket: 163094
+    "ov::float16"
+    "ov::EncryptionCallbacks"
+    "ov::streams::Num"
+    "ov::pass::pattern::PatternSymbolValue"
+
+    # Other issues, ticket: 163094
+    "<Dimension:"
+    "dynamic"
+    "<RTMap>"
+)
+
+invalid_identifiers=(
+    # Ticket: 163093
+    "<locals>"
+)
+
+unresolved_names=(
+    # Circular dependencies, ticket: 163078
+    "InferRequestWrapper"
+
+    # Other issues, ticket: 163094
+    "RemoteTensorWrapper"
+    "capsule"
+    "VASurfaceTensorWrapper"
+    "_abc._abc_data"
+    "openvino._ov_api.undefined_deprecated"
+    "InputCutInfo"
+    "ParamData"
+)
+
+create_regex_pattern() {
+    local errors=("$@")
+    local regex_pattern=""
+
+    for error in "${errors[@]}"; do
+        escaped_error=$(printf '%s\n' "$error" | sed -e 's/[]\/$*.^|[]/\\&/g')
+        regex_pattern+=".*$escaped_error.*|"
+    done
+    regex_pattern="${regex_pattern%|}"
+    echo "$regex_pattern"
+}
+
+invalid_expressions_regex=$(create_regex_pattern "${invalid_expressions[@]}")
+invalid_identifiers_regex=$(create_regex_pattern "${invalid_identifiers[@]}")
+unresolved_names_regex=$(create_regex_pattern "${unresolved_names[@]}")
+
+# Set the output directory
+if [ -z "$1" ]; then
+    output_dir="$(dirname "$0")/../src"
+else
+    output_dir="$1"
+fi
+
+# Generate stubs for C++ bindings
+if ! python -m pybind11_stubgen \
+            --output-dir "$output_dir" \
+            --root-suffix "" \
+            --ignore-invalid-expressions "$invalid_expressions_regex" \
+            --ignore-invalid-identifiers "$invalid_identifiers_regex" \
+            --ignore-unresolved-names "$unresolved_names_regex" \
+            --numpy-array-use-type-var \
+            --exit-code \
+            openvino; then
+    echo "Error: pybind11-stubgen failed."
+    exit 1
+fi
+
+# Workaround for pybind11-stubgen issue where it doesn't import some modules for stubs generated from .py files 
+# Ticket: 163225
+pyi_file="$output_dir/openvino/_ov_api.pyi"
+if [ -f "$pyi_file" ]; then
+    sed -i '2i import typing' "$pyi_file"
+    sed -i '2i import pathlib' "$pyi_file"
+else
+    echo "File $pyi_file not found."
+    exit 1
+fi
+
+# Find all changed .pyi files
+changed_files=$(git diff --name-only | grep '\.pyi$')
+# Process each changed .pyi file
+for file in $changed_files; do
+    sed -i 's/<function _get_node_factory at 0x[0-9a-fA-F]\+>/<function _get_node_factory at memory_address>/' "$file"
+    sed -i "s/__version__: str = '[^']*'/__version__: str = 'version_string'/" "$file"
+    sed -i 's/<function <lambda> at 0x[0-9a-fA-F]\{1,\}>/<function <lambda> at memory_address>/g' "$file"
+    sed -i 's/: \.\.\./: typing.Any/g' "$file" 
+    sed -i 's/pass: MatcherPass/matcher_pass: MatcherPass/g' "$file"
+    # Sort consecutive import statements
+    awk '
+    BEGIN { in_imports = 0; }
+    /^from / || /^import / {
+        if (in_imports == 0) {
+            start = NR;
+        }
+        in_imports++;
+        imports[in_imports] = $0;
+        next;
+    }
+    {
+        if (in_imports > 0) {
+            for (i = 1; i <= in_imports; i++) {
+                print imports[i] | "sort";
+            }
+            close("sort");
+            in_imports = 0;
+        }
+        print;
+    }
+    END {
+        if (in_imports > 0) {
+            for (i = 1; i <= in_imports; i++) {
+                print imports[i] | "sort"; 
+            }
+            close("sort");
+        }
+    }
+    ' "$file" > "$file.sorted"
+    mv "$file.sorted" "$file"
+    sed -i '1i # type: ignore' "$file"
+done

src/bindings/python/scripts/stub_generation_precommit.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: local
+    hooks:
+      - id: generate_stubs
+        name: Generate .pyi files
+        language: system
+        entry: >
+          bash -c 'if [[ "$OSTYPE" == "msys" ]]; then
+            "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/src/bindings/python/scripts/generate_pyapi_stubs.bat";
+          else
+            "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/src/bindings/python/scripts/generate_pyapi_stubs.sh";
+          fi;
+          if [ $? -ne 0 ]; then
+            echo "Stub generation failed. Aborting commit.";
+            exit 1;
+          fi;
+
+          git add ./*.pyi'
+        files: .*src/bindings/python/.*
+        pass_filenames: false
+        verbose: true
+        stages: [pre-commit]