feat: add type hints to paddleocr/ public API (Phase 1)

Add comprehensive type annotations across the entire paddleocr/ package
for IDE autocompletion and static type checking support.

- Add PEP 561 py.typed marker and shared _types.py (ImageInput, InputType, PredictResult)
- Annotate all model base classes, mixins, and 13 model subclasses
- Annotate all pipeline base, utils, and 10 pipeline subclasses
- Annotate utility modules (_utils/cli, deprecation, logging) and core modules
- Add mypy configuration in pyproject.toml (Python 3.8 compat via `from __future__ import annotations`)
- Add mypy type check step to CI codestyle workflow

Author: scyyh11

.github/workflows/codestyle.yml

@@ -34,3 +34,8 @@ jobs:
     - uses: pre-commit/action@v3.0.1
       with:
         extra_args: '--all-files'
+
+    - name: Type check with mypy
+      run: |
+        pip install mypy numpy
+        mypy paddleocr/

paddleocr/__main__.py

@@ -18,7 +18,7 @@
 from ._cli import main
 
 
-def console_entry() -> int:
+def console_entry() -> None:
     # See https://docs.python.org/3/library/signal.html#note-on-sigpipe
     try:
         # Flush output here to force SIGPIPE to be triggered while inside this

paddleocr/_abstract.py

@@ -12,14 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import abc
+import argparse
+from typing import Any
 
 
 class CLISubcommandExecutor(metaclass=abc.ABCMeta):
     @abc.abstractmethod
-    def add_subparser(self, subparsers):
+    def add_subparser(self, subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
         raise NotImplementedError
 
     @abc.abstractmethod
-    def execute_with_args(self, args):
+    def execute_with_args(self, args: argparse.Namespace) -> None:
         raise NotImplementedError

paddleocr/_common_args.py

@@ -12,6 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
 from paddlex.inference import PaddlePredictorOption
 from paddlex.utils.device import get_default_device, parse_device
 
@@ -28,7 +33,7 @@
 from ._utils.cli import str2bool
 
 
-def parse_common_args(kwargs, *, default_enable_hpi):
+def parse_common_args(kwargs: dict[str, Any], *, default_enable_hpi: bool | None) -> dict[str, Any]:
     default_vals = {
         "device": DEFAULT_DEVICE,
         "enable_hpi": default_enable_hpi,
@@ -57,13 +62,13 @@ def parse_common_args(kwargs, *, default_enable_hpi):
     return kwargs
 
 
-def prepare_common_init_args(model_name, common_args):
+def prepare_common_init_args(model_name: str | None, common_args: dict[str, Any]) -> dict[str, Any]:
     device = common_args["device"]
     if device is None:
         device = get_default_device()
     device_type, _ = parse_device(device)
 
-    init_kwargs = {}
+    init_kwargs: dict[str, Any] = {}
     init_kwargs["device"] = device
     init_kwargs["use_hpip"] = common_args["enable_hpi"]
 
@@ -94,7 +99,7 @@ def prepare_common_init_args(model_name, common_args):
     return init_kwargs
 
 
-def add_common_cli_opts(parser, *, default_enable_hpi, allow_multiple_devices):
+def add_common_cli_opts(parser: argparse.ArgumentParser, *, default_enable_hpi: bool | None, allow_multiple_devices: bool) -> None:
     if allow_multiple_devices:
         help_ = "Device(s) to use for inference, e.g., `cpu`, `gpu`, `npu`, `gpu:0`, `gpu:0,1`. If multiple devices are specified, inference will be performed in parallel. Note that parallel inference is not always supported. By default, GPU 0 will be used if available; otherwise, the CPU will be used."
     else:

paddleocr/_constants.py

@@ -12,11 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-DEFAULT_DEVICE = None
-DEFAULT_USE_TENSORRT = False
-DEFAULT_PRECISION = "fp32"
-DEFAULT_ENABLE_MKLDNN = True
-DEFAULT_MKLDNN_CACHE_CAPACITY = 10
-DEFAULT_CPU_THREADS = 10
-SUPPORTED_PRECISION_LIST = ["fp32", "fp16"]
-DEFAULT_USE_CINN = False
+from __future__ import annotations
+
+DEFAULT_DEVICE: str | None = None
+DEFAULT_USE_TENSORRT: bool = False
+DEFAULT_PRECISION: str = "fp32"
+DEFAULT_ENABLE_MKLDNN: bool = True
+DEFAULT_MKLDNN_CACHE_CAPACITY: int = 10
+DEFAULT_CPU_THREADS: int = 10
+SUPPORTED_PRECISION_LIST: list[str] = ["fp32", "fp16"]
+DEFAULT_USE_CINN: bool = False

paddleocr/_env.py

@@ -12,8 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import os
 
-DISABLE_AUTO_LOGGING_CONFIG = (
+DISABLE_AUTO_LOGGING_CONFIG: bool = (
     os.getenv("PADDLEOCR_DISABLE_AUTO_LOGGING_CONFIG", "0") == "1"
 )

paddleocr/_models/_doc_vlm.py

@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import abc
+import argparse
+from typing import Any
 
 from .._utils.cli import (
     get_subcommand_args,
@@ -25,13 +29,13 @@
 class BaseDocVLM(PaddleXPredictorWrapper):
     def __init__(
         self,
-        *args,
-        **kwargs,
-    ):
-        self._extra_init_args = {}
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self._extra_init_args: dict[str, Any] = {}
         super().__init__(*args, **kwargs)
 
-    def _get_extra_paddlex_predictor_init_args(self):
+    def _get_extra_paddlex_predictor_init_args(self) -> dict[str, Any]:
         return self._extra_init_args
 
 
@@ -40,10 +44,10 @@ class BaseDocVLMSubcommandExecutor(PredictorCLISubcommandExecutor):
 
     @property
     @abc.abstractmethod
-    def wrapper_cls(self):
+    def wrapper_cls(self) -> type[PaddleXPredictorWrapper]:
         raise NotImplementedError
 
-    def execute_with_args(self, args):
+    def execute_with_args(self, args: argparse.Namespace) -> None:
         params = get_subcommand_args(args)
         params["input"] = self.input_validator(params["input"])
         perform_simple_inference(self.wrapper_cls, params)

paddleocr/_models/_image_classification.py

@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import abc
+import argparse
+from typing import Any
 
 from .._utils.cli import (
     add_simple_inference_args,
@@ -26,20 +30,20 @@ class ImageClassification(PaddleXPredictorWrapper):
     def __init__(
         self,
         *,
-        topk=None,
-        **kwargs,
-    ):
+        topk: int | None = None,
+        **kwargs: Any,
+    ) -> None:
         self._extra_init_args = {
             "topk": topk,
         }
         super().__init__(**kwargs)
 
-    def _get_extra_paddlex_predictor_init_args(self):
+    def _get_extra_paddlex_predictor_init_args(self) -> dict[str, Any]:
         return self._extra_init_args
 
 
 class ImageClassificationSubcommandExecutor(PredictorCLISubcommandExecutor):
-    def _update_subparser(self, subparser):
+    def _update_subparser(self, subparser: argparse.ArgumentParser) -> None:
         add_simple_inference_args(subparser)
 
         subparser.add_argument(
@@ -50,9 +54,9 @@ def _update_subparser(self, subparser):
 
     @property
     @abc.abstractmethod
-    def wrapper_cls(self):
+    def wrapper_cls(self) -> type[PaddleXPredictorWrapper]:
         raise NotImplementedError
 
-    def execute_with_args(self, args):
+    def execute_with_args(self, args: argparse.Namespace) -> None:
         params = get_subcommand_args(args)
         perform_simple_inference(self.wrapper_cls, params)

paddleocr/_models/_object_detection.py

@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import abc
+import argparse
+from typing import Any
 
 from .._utils.cli import (
     add_simple_inference_args,
@@ -27,13 +31,13 @@ class ObjectDetection(PaddleXPredictorWrapper):
     def __init__(
         self,
         *,
-        img_size=None,
-        threshold=None,
-        layout_nms=None,
-        layout_unclip_ratio=None,
-        layout_merge_bboxes_mode=None,
-        **kwargs,
-    ):
+        img_size: int | None = None,
+        threshold: float | None = None,
+        layout_nms: bool | None = None,
+        layout_unclip_ratio: float | None = None,
+        layout_merge_bboxes_mode: str | None = None,
+        **kwargs: Any,
+    ) -> None:
         self._extra_init_args = {
             "img_size": img_size,
             "threshold": threshold,
@@ -43,12 +47,12 @@ def __init__(
         }
         super().__init__(**kwargs)
 
-    def _get_extra_paddlex_predictor_init_args(self):
+    def _get_extra_paddlex_predictor_init_args(self) -> dict[str, Any]:
         return self._extra_init_args
 
 
 class ObjectDetectionSubcommandExecutor(PredictorCLISubcommandExecutor):
-    def _update_subparser(self, subparser):
+    def _update_subparser(self, subparser: argparse.ArgumentParser) -> None:
         add_simple_inference_args(subparser)
 
         subparser.add_argument(
@@ -79,9 +83,9 @@ def _update_subparser(self, subparser):
 
     @property
     @abc.abstractmethod
-    def wrapper_cls(self):
+    def wrapper_cls(self) -> type[PaddleXPredictorWrapper]:
         raise NotImplementedError
 
-    def execute_with_args(self, args):
+    def execute_with_args(self, args: argparse.Namespace) -> None:
         params = get_subcommand_args(args)
         perform_simple_inference(self.wrapper_cls, params)

paddleocr/_models/_text_detection.py

@@ -12,19 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
 
 class TextDetectionMixin:
     def __init__(
         self,
         *,
-        limit_side_len=None,
-        limit_type=None,
-        thresh=None,
-        box_thresh=None,
-        unclip_ratio=None,
-        input_shape=None,
-        **kwargs,
-    ):
+        limit_side_len: int | None = None,
+        limit_type: str | None = None,
+        thresh: float | None = None,
+        box_thresh: float | None = None,
+        unclip_ratio: float | None = None,
+        input_shape: tuple[int, int, int] | None = None,
+        **kwargs: Any,
+    ) -> None:
         self._extra_init_args = {
             "limit_side_len": limit_side_len,
             "limit_type": limit_type,
@@ -35,12 +40,12 @@ def __init__(
         }
         super().__init__(**kwargs)
 
-    def _get_extra_paddlex_predictor_init_args(self):
+    def _get_extra_paddlex_predictor_init_args(self) -> dict[str, Any]:
         return self._extra_init_args
 
 
 class TextDetectionSubcommandExecutorMixin:
-    def _add_text_detection_args(self, subparser):
+    def _add_text_detection_args(self, subparser: argparse.ArgumentParser) -> None:
         subparser.add_argument(
             "--limit_side_len",
             type=int,