Merge pull request #24023 from VadimLevin:dev/vlevin/python-typing-magic-constants

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

modules/python/src2/typing_stubs_generation/api_refinement.py

@@ -20,6 +20,8 @@ def apply_manual_api_refinement(root: NamespaceNode) -> None:
     root.add_class("error", (builtin_exception, ), ERROR_CLASS_PROPERTIES)
     for symbol_name, refine_symbol in NODES_TO_REFINE.items():
         refine_symbol(root, symbol_name)
+    version_constant = root.add_constant("__version__", "<unused>")
+    version_constant._value_type = "str"
 
 
 def export_matrix_type_constants(root: NamespaceNode) -> None:

modules/python/src2/typing_stubs_generation/generation.py

@@ -101,6 +101,9 @@ def _generate_typing_stubs(root: NamespaceNode, output_path: Path) -> None:
 
     output_stream = StringIO()
 
+    # Add empty __all__ dunder on top of the module
+    output_stream.write("__all__: list[str] = []\n\n")
+
     # Write required imports at the top of file
     _write_required_imports(required_imports, output_stream)
 
@@ -318,6 +321,10 @@ def _generate_constant_stub(constant_node: ConstantNode,
     export_name = extra_export_prefix + constant_node.export_name
     write_constant_to_stream(export_name)
     if generate_uppercase_version:
+        # Handle Python "magic" constants like __version__
+        if re.match(r"^__.*__$", export_name) is not None:
+            return export_name,
+
         uppercase_name = re.sub(r"([a-z])([A-Z])", r"\1_\2", export_name).upper()
         if export_name != uppercase_name:
             write_constant_to_stream(uppercase_name)

modules/python/src2/typing_stubs_generation/nodes/constant_node.py

@@ -11,6 +11,7 @@ class ConstantNode(ASTNode):
                  export_name: Optional[str] = None) -> None:
         super().__init__(name, parent, export_name)
         self.value = value
+        self._value_type = "int"
 
     @property
     def children_types(self) -> Tuple[Type[ASTNode], ...]:
@@ -22,7 +23,7 @@ class ConstantNode(ASTNode):
 
     @property
     def value_type(self) -> str:
-        return 'int'
+        return self._value_type
 
     def __str__(self) -> str:
         return "Constant('{}' exported as '{}': {})".format(