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)
SequenceTypeNode and ClassTypeNode always format as _typing.Sequence[...]
and _typing.Type[...], but ContainerTypeNode only reports the typing
import as required when compatible_to_runtime_usage is set. Stubs for
modules that use these nodes without any other _typing usage (e.g.
cv2/videoio_registry) reference _typing without importing it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When a module is disabled in an incremental build (e.g. switching from
-DBUILD_opencv_gapi=ON to OFF), its typing stub directory persists from
the previous build. The stubs generator only creates directories for
enabled modules but never removes old ones, and the copy step merges
rather than replaces, so stale .pyi files propagate to both the loader
directory and the install prefix.
This causes type-checkers (mypy, pyright) to report errors for stubs
that reference symbols from modules that are no longer available.
Fix both propagation paths:
- generation.py: remove all subdirectories under the stubs output root
before regenerating, so only currently enabled module stubs exist in
the build directory. Top-level files (py.typed) are preserved.
- copy_typings_stubs_on_success.py: remove stale .pyi files and
py.typed markers from the loader directory before copying fresh stubs,
so leftover stubs from a previous copy are cleaned up. Runtime .py
files are not affected.
Fix two issues that cause `import cv2` to fail when building with
-DBUILD_opencv_gapi=OFF:
1. In `has_all_required_modules()`, the function parameter `type_node`
was ignored in favor of the enclosing scope's loop variable `node`.
This works by accident when called as `has_all_required_modules(node)`
but is incorrect — the parameter should be used directly.
2. In `__load_extra_py_code_for_module()`, only `ImportError` was
caught. When a stale gapi submodule directory exists from a previous
build, gapi/__init__.py raises `AttributeError` (not `ImportError`)
because it tries to access C++ bindings that don't exist. Now catches
both exception types for defense-in-depth.
Refs: #26098
imgproc: fix HoughCircles Python return type to allow None #28621
### 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
### Description
Fixes https://github.com/opencv/opencv/issues/28528
`HoughCircles` returns `None` when no circles are found, but the auto-generated Python type stub declares the return type as `MatLike` without `None`. This causes type checkers (mypy/pyright) to miss potential `None` dereferences.
**Fix:** Add `HoughCircles` to `NODES_TO_REFINE` in `api_refinement.py` using the existing `make_optional_none_return` helper - the same pattern already used for `imread` and `imdecode`.
This contribution was developed with AI assistance (Claude Code).
Fix inRange type signature to accept Scalar values #28536Fixes#28534
The Python type signature for cv2.inRange was too restrictive, requiring MatLike for lowerb and upperb parameters. However, the C++ implementation accepts InputArray which includes Scalar values (tuples, floats, etc.).
This caused type checkers to incorrectly flag valid code from official tutorials as type errors.
Added make_matlike_or_scalar_arg() refinement function to create union types MatLike | Scalar for affected parameters, matching the C++ InputArray behavior.
### 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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Fix Python Scalar typing issue #27528#27620
- Add ScalarInput and ScalarOutput types for better type safety
- ScalarInput: Union[Sequence[float], float] for function parameters
- ScalarOutput: Sequence[float] for function return values
- Keep original Scalar type for backwards compatibility (deprecated)
- Add refinement functions to apply new types to specific functions
- Functions returning scalars now use ScalarOutput (mean, sumElems, trace)
- Drawing functions now use ScalarInput for color parameters
- Resolves MyPy compatibility issues with scalar return values
- Maintains full backwards compatibility
closes#27528
### 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.
- [x ] The feature is well documented and sample code can be built with the project CMake
Consider QRCode ECI encoding #24426
### Pull Request Readiness Checklist
related: https://github.com/opencv/opencv/pull/24350#pullrequestreview-1661658421
1. Add `getEncoding` method to obtain ECI number
2. Add `detectAndDecodeBytes`, `decodeBytes`, `decodeBytesMulti`, `detectAndDecodeBytesMulti` methods in Python (return `bytes`) and Java (return `byte[]`)
3. Allow Python bytes to std::string conversion in general and add `encode(byte[] encoded_info, Mat qrcode)` in Java
Python example with Kanji encoding:
```python
img = cv.imread("test.png")
detect = cv.QRCodeDetector()
data, points, straight_qrcode = detect.detectAndDecodeBytes(img)
print(data)
print(detect.getEncoding(), cv.QRCodeEncoder_ECI_SHIFT_JIS)
print(data.decode("shift-jis"))
```
```
b'\x82\xb1\x82\xf1\x82\xc9\x82\xbf\x82\xcd\x90\xa2\x8aE'
20 20
こんにちは世界
```
source: ba4d6c859d/modules/objdetect/test/test_qrcode_encode.cpp (L332)
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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Java VideoCapture buffered stream constructor #27284
### Pull Request Readiness Checklist
resolves#26809
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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Removed g-api from the main repo #26469
Following #25000.
CI patch: https://github.com/opencv/ci-gha-workflow/pull/196
This is migration of G-API from opencv to opencv_contrib, part 1.
Here we simply remove G-API from the main repo. The next patch should bring G-API to opencv_contrib.
- [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
int64 data type support for FileStorage. 1d and empty Mat with exact dimensions #26434
### Pull Request Readiness Checklist
Port of https://github.com/opencv/opencv/pull/26399 to 4.x branch
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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
int64 data type in FileStorage #26399
### Pull Request Readiness Checklist
resolves#23333
Proposed approach is not perfect in terms of complexity and potential bugs. Instead of changing `INT` raw size from `4` to `8`, we check int64 value can be fitted to int32 or not.
Collections such as cv::Mat rely on data type symbol.
This PR is addressed to 5.x branch first to cover `CV_64S` Mat. Later, it can be backported to 4.x
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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Add support for boolan input/outputs in python bindings #26026
This PR add support boolean input/output binding in python. The issue what mention in ticket https://github.com/opencv/opencv/issues/26024 and the PR soleves it. Data and models are located in [here](https://github.com/opencv/opencv_extra/pull/1201)
### 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
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Python typing refinement for dnn_registerLayer/dnn_unregisterLayer functions #24066
This patch introduces typings generation for `dnn_registerLayer`/`dnn_unregisterLayer` manually defined in [`cv2/modules/dnn/misc/python/pyopencv_dnn.hpp`](https://github.com/opencv/opencv/blob/4.x/modules/dnn/misc/python/pyopencv_dnn.hpp)
Updates:
- Add `LayerProtocol` to `cv2/dnn/__init__.pyi`:
```python
class LayerProtocol(Protocol):
def __init__(
self, params: dict[str, DictValue],
blobs: typing.Sequence[cv2.typing.MatLike]
) -> None: ...
def getMemoryShapes(
self, inputs: typing.Sequence[typing.Sequence[int]]
) -> typing.Sequence[typing.Sequence[int]]: ...
def forward(
self, inputs: typing.Sequence[cv2.typing.MatLike]
) -> typing.Sequence[cv2.typing.MatLike]: ...
```
- Add `dnn_registerLayer` function to `cv2/__init__.pyi`:
```python
def dnn_registerLayer(layerTypeName: str,
layerClass: typing.Type[LayerProtocol]) -> None: ...
```
- Add `dnn_unregisterLayer` function to `cv2/__init__.pyi`:
```python
def dnn_unregisterLayer(layerTypeName: str) -> None: ...
```
### 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
- [ ] 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.
- [x] The feature is well documented and sample code can be built with the project CMake
Python typing magic constants #24023
This patch adds typing stubs generation for `__all__` and `__version__` constants.
Introduced `__all__` is intentionally empty for all generated modules stubs.
Type hints won't work for star imports
resolves#23950
### 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.
- [x] The feature is well documented and sample code can be built with the project CMake
Fix python typing stubs generation for CUDA modules #24022resolves#23946resolves#23945resolvesopencv/opencv-python#871
### 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.
- [x] The feature is well documented and sample code can be built with the project CMake
Adds missing typing stubs:
- Matrix depths: `CV_8U`, `CV_8S` and etc.
- Matrix type constants: `CV_8UC1`, `CV_32FC3` and etc.
- Matrix type factory functions: `CV_*(channels) -> int` and `CV_MAKETYPE`
