From 41ef839c7d03231dc40c026d28e1ba80494f506d Mon Sep 17 00:00:00 2001 From: Kari Pikkarainen <154351964+kari-pikkarainen@users.noreply.github.com> Date: Mon, 5 Oct 2026 22:40:49 -0700 Subject: [PATCH] Merge pull request #30148 from kari-pikkarainen:fix/python-stubs-optional-output-args-5.x MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit python: mark documented None output arrays as optional in typing stubs (5.x) 🤖🤖🤖 - #30148 Port of #30139 to 5.x, as requested in https://github.com/opencv/opencv/pull/30139#issuecomment-5994064397. Relates to #30138. The two commits are cherry-picked from #30139 without code changes. The second commit message is reworded for the 5.x module layout. **Commit 1:** adds `make_optional_arg` entries to `NODES_TO_REFINE` in `modules/python/src2/typing_stubs_generation/api_refinement.py`. These output arrays are documented and used with `None` in the 5.x samples and tutorials, but the stubs type them as required, so mypy rejects correct code: | Function | Argument | |---|---| | `calcOpticalFlowPyrLK` | `nextPts` | | `calcOpticalFlowFarneback` | `flow` | | `normalize` | `dst` | | `kmeans` | `bestLabels` | | `drawKeypoints` | `outImage` | | `drawMatches` | `outImg` | | `drawMatchesKnn` | `outImg` | **Commit 2:** skips `NODES_TO_REFINE` entries whose function, class or namespace is absent from the build, as the `dnn`/`cuda` refinements already do. On 5.x this also fixes an existing failure: with `-DBUILD_opencv_calib=OFF`, the `calibrateCamera` entry raises `SymbolNotFoundError` and no stubs are generated at all. A wrong argument name in a present function still raises `RuntimeError`. ### Verification I ran CMake configure only, then `gen2.py` from this branch and from `5.x` (2d88732) on the generated `gen_python_config.json`, with `PYTHONHASHSEED=0`: - **Full build:** the only differences are 16 signatures in `cv2/__init__.pyi`. Each listed argument changes from `cv2.typing.MatLike` / `UMat` to `... | None`, across the Mat and UMat overloads, and `drawMatches` has two C++ overloads. - **`-DBUILD_opencv_video=OFF`:** stubs are generated. The two optical-flow entries are skipped and the other refinements still apply. - **`-DBUILD_opencv_calib=OFF`:** `5.x` generates no stubs (`SymbolNotFoundError` for `calibrateCamera`). This branch generates them. - **mypy 2.4.0:** I installed the generated stubs as a stub-only package and type-checked calls that pass `None` for each argument, e.g. `cv2.normalize(img, None, 0, 255, cv2.NORM_MINMAX)`. With the `5.x` stubs there are 11 `call-overload` errors; with this branch there are none. Builds without `features` still fail for a separate reason, the `Feature2D` aliases in `predefined_types.py`. I'll address that in a follow-up. _Prepared with AI assistance (Claude Code); I reviewed the change and the verification results._ ### Pull Request Readiness Checklist See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request - [x] I agree to contribute to the project under Apache 2 License. - [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV - [x] The PR is proposed to the proper branch - [x] There is a reference to the original bug report and related work - [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable Patch to opencv_extra has the same branch name. - [ ] The feature is well documented and sample code can be built with the project CMake 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- .../typing_stubs_generation/api_refinement.py | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/modules/python/src2/typing_stubs_generation/api_refinement.py b/modules/python/src2/typing_stubs_generation/api_refinement.py index 60ab2ba78b..9485a9621b 100644 --- a/modules/python/src2/typing_stubs_generation/api_refinement.py +++ b/modules/python/src2/typing_stubs_generation/api_refinement.py @@ -10,7 +10,8 @@ from .nodes import (NamespaceNode, FunctionNode, OptionalTypeNode, TypeNode, TupleTypeNode, UnionTypeNode, ProtocolClassNode, DictTypeNode, ClassTypeNode, AliasRefTypeNode) from .ast_utils import (find_function_node, SymbolName, - for_each_function_overload) + for_each_function_overload, ScopeNotFoundError, + SymbolNotFoundError) from .types_conversion import create_type_node @@ -24,7 +25,11 @@ def apply_manual_api_refinement(root: NamespaceNode) -> None: builtin_exception.is_exported = False root.add_class("error", (builtin_exception, ), ERROR_CLASS_PROPERTIES) for symbol_name, refine_symbol in NODES_TO_REFINE.items(): - refine_symbol(root, symbol_name) + try: + refine_symbol(root, symbol_name) + except (ScopeNotFoundError, SymbolNotFoundError): + # Function is not part of this build, e.g. its module is disabled + continue version_constant = root.add_constant("__version__", "") version_constant._value_type = "str" @@ -455,6 +460,13 @@ NODES_TO_REFINE = { SymbolName(("cv", ), (), "undistortPoints"): make_optional_arg("distCoeffs"), SymbolName(("cv", ), (), "calibrateCamera"): make_optional_arg("cameraMatrix", "distCoeffs"), SymbolName(("cv", "fisheye"), (), "initUndistortRectifyMap"): make_optional_arg("D"), + SymbolName(("cv", ), (), "calcOpticalFlowPyrLK"): make_optional_arg("nextPts"), + SymbolName(("cv", ), (), "calcOpticalFlowFarneback"): make_optional_arg("flow"), + SymbolName(("cv", ), (), "normalize"): make_optional_arg("dst"), + SymbolName(("cv", ), (), "kmeans"): make_optional_arg("bestLabels"), + SymbolName(("cv", ), (), "drawKeypoints"): make_optional_arg("outImage"), + SymbolName(("cv", ), (), "drawMatches"): make_optional_arg("outImg"), + SymbolName(("cv", ), (), "drawMatchesKnn"): make_optional_arg("outImg"), SymbolName(("cv", ), (), "imread"): make_optional_none_return, SymbolName(("cv", ), (), "imdecode"): make_optional_none_return, SymbolName(("cv", ), (), "HoughCircles"): make_optional_none_return,