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

Add type annotations to all public modules in paddleocr/ using
Python 3.8 compatible typing (List, Dict, Tuple, Optional, Union).
Configure mypy for CI and add py.typed marker.

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

@@ -13,13 +13,17 @@
 # limitations under the License.
 
 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/_cli.py

@@ -19,6 +19,7 @@
 import time
 import warnings
 from threading import Thread
+from typing import Any
 
 import requests
 
@@ -54,7 +55,7 @@
 from ._utils.logging import logger
 
 
-def _register_pipelines(subparsers):
+def _register_pipelines(subparsers: argparse._SubParsersAction) -> None:
     for cls in [
         DocPreprocessor,
         DocUnderstanding,
@@ -67,12 +68,12 @@ def _register_pipelines(subparsers):
         SealRecognition,
         TableRecognitionPipelineV2,
     ]:
-        subcommand_executor = cls.get_cli_subcommand_executor()
+        subcommand_executor = cls.get_cli_subcommand_executor()  # type: ignore[attr-defined]
         subparser = subcommand_executor.add_subparser(subparsers)
         subparser.set_defaults(executor=subcommand_executor.execute_with_args)
 
 
-def _register_models(subparsers):
+def _register_models(subparsers: argparse._SubParsersAction) -> None:
     for cls in [
         ChartParsing,
         DocImgOrientationClassification,
@@ -88,13 +89,13 @@ def _register_models(subparsers):
         TextLineOrientationClassification,
         TextRecognition,
     ]:
-        subcommand_executor = cls.get_cli_subcommand_executor()
+        subcommand_executor = cls.get_cli_subcommand_executor()  # type: ignore[attr-defined]
         subparser = subcommand_executor.add_subparser(subparsers)
         subparser.set_defaults(executor=subcommand_executor.execute_with_args)
 
 
-def _register_install_hpi_deps_command(subparsers):
-    def _install_hpi_deps(args):
+def _register_install_hpi_deps_command(subparsers: argparse._SubParsersAction) -> None:
+    def _install_hpi_deps(args: argparse.Namespace) -> None:
         hpip = f"hpi-{args.variant}"
         try:
             subprocess.check_call(["paddlex", "--install", hpip])
@@ -107,8 +108,10 @@ def _install_hpi_deps(args):
     subparser.set_defaults(executor=_install_hpi_deps)
 
 
-def _register_install_genai_server_deps_command(subparsers):
-    def _install_genai_server_deps(args):
+def _register_install_genai_server_deps_command(
+    subparsers: argparse._SubParsersAction,
+) -> None:
+    def _install_genai_server_deps(args: argparse.Namespace) -> None:
         try:
             subprocess.check_call(
                 ["paddlex", "--install", f"genai-{args.variant}-server"]
@@ -123,14 +126,14 @@ def _install_genai_server_deps(args):
     subparser.set_defaults(executor=_install_genai_server_deps)
 
 
-def _register_genai_server_command(subparsers):
+def _register_genai_server_command(subparsers: argparse._SubParsersAction) -> None:
     # TODO: Register the subparser whether the plugin is installed or not
     try:
         from paddlex.inference.genai.server import get_arg_parser, run_genai_server
     except RuntimeError:
         return
 
-    def _show_prompt_when_server_is_running(host, port, backend):
+    def _show_prompt_when_server_is_running(host: str, port: int, backend: str) -> None:
         if host == "0.0.0.0":
             host = "localhost"
         while True:
@@ -147,7 +150,7 @@ def _show_prompt_when_server_is_running(host, port, backend):
     2. Make HTTP requests directly, or using the OpenAI client library."""
         logger.info(prompt)
 
-    def _run_genai_server(args):
+    def _run_genai_server(args: argparse.Namespace) -> None:
         Thread(
             target=_show_prompt_when_server_is_running,
             args=(args.host, args.port, args.backend),
@@ -165,7 +168,7 @@ def _run_genai_server(args):
     subparser.set_defaults(executor=_run_genai_server)
 
 
-def _get_parser():
+def _get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="paddleocr")
     parser.add_argument(
         "-v", "--version", action="version", version=f"%(prog)s {version}"
@@ -179,11 +182,11 @@ def _get_parser():
     return parser
 
 
-def _execute(args):
+def _execute(args: argparse.Namespace) -> None:
     args.executor(args)
 
 
-def main():
+def main() -> None:
     logger.setLevel(logging.INFO)
     warnings.filterwarnings("default", category=CLIDeprecationWarning)
     parser = _get_parser()

paddleocr/_common_args.py

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import argparse
+from typing import Any, Dict, Optional
+
 from paddlex.inference import PaddlePredictorOption
 from paddlex.utils.device import get_default_device, parse_device
 
@@ -28,7 +31,9 @@
 from ._utils.cli import str2bool
 
 
-def parse_common_args(kwargs, *, default_enable_hpi):
+def parse_common_args(
+    kwargs: Dict[str, Any], *, default_enable_hpi: Optional[bool]
+) -> Dict[str, Any]:
     default_vals = {
         "device": DEFAULT_DEVICE,
         "enable_hpi": default_enable_hpi,
@@ -57,13 +62,15 @@ 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: Optional[str], 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 +101,12 @@ 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: Optional[bool],
+    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

@@ -1,3 +1,5 @@
+from typing import List, Optional
+
 # Copyright (c) 2025 PaddlePaddle Authors. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,11 +14,11 @@
 # 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
+DEFAULT_DEVICE: Optional[str] = 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

@@ -14,6 +14,6 @@
 
 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

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import abc
+import argparse
+from typing import Any, Dict, Type
 
 from .._utils.cli import (
     get_subcommand_args,
@@ -25,13 +27,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 +42,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

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import abc
+import argparse
+from typing import Any, Dict, Optional, Type
 
 from .._utils.cli import (
     add_simple_inference_args,
@@ -26,20 +28,20 @@ class ImageClassification(PaddleXPredictorWrapper):
     def __init__(
         self,
         *,
-        topk=None,
-        **kwargs,
-    ):
+        topk: Optional[int] = 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 +52,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

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import abc
+import argparse
+from typing import Any, Dict, Optional, Tuple, Type, Union
 
 from .._utils.cli import (
     add_simple_inference_args,
@@ -27,13 +29,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: Optional[Union[int, Tuple[int, int]]] = None,
+        threshold: Optional[Union[float, dict]] = None,
+        layout_nms: Optional[bool] = None,
+        layout_unclip_ratio: Optional[Union[float, Tuple[float, float], dict]] = None,
+        layout_merge_bboxes_mode: Optional[Union[str, dict]] = None,
+        **kwargs: Any,
+    ) -> None:
         self._extra_init_args = {
             "img_size": img_size,
             "threshold": threshold,
@@ -43,12 +45,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 +81,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)