🎨 style: lint and format

.vscode/settings.json

@@ -1,8 +1,9 @@
 {
   "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
-  "python.formatting.provider": "black",
-  "python.formatting.blackArgs": ["--line-length", "120"],
   "python.analysis.typeCheckingMode": "strict",
   "python.analysis.inlayHints.functionReturnTypes": true,
-  "python.analysis.inlayHints.variableTypes": true
+  "python.analysis.inlayHints.variableTypes": true,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
 }

dochooks/_compat.py

@@ -1,35 +1,12 @@
 from __future__ import annotations
 
-try:
-    from typing import Literal  # type: ignore
-except ImportError:
-    from typing_extensions import Literal  # type: ignore
+import sys
 
-try:
-    from typing import Final  # type: ignore
-except ImportError:
-    from typing_extensions import Final  # type: ignore
-
-try:
-    from typing import TypeAlias  # type: ignore
-except ImportError:
-    from typing_extensions import TypeAlias  # type: ignore
-
-try:
-    from typing import TypedDict  # type: ignore
-except ImportError:
-    from typing_extensions import TypedDict  # type: ignore
-
-try:
-    from typing import assert_type  # type: ignore
-except ImportError:
-    from typing_extensions import assert_type  # type: ignore
-
-try:
+if sys.version_info >= (3, 9):
     from functools import cache  # type: ignore
-except ImportError:
+else:
     from functools import lru_cache  # type: ignore
 
     cache = lru_cache(maxsize=None)
 
-__all__ = ["Literal", "Final", "TypeAlias", "TypedDict", "assert_type", "cache"]
+__all__ = ["cache"]

dochooks/api_doc_checker/check.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import argparse
-from typing import Optional, Sequence
+from typing import Sequence
 
 from dochooks import __version__
 
@@ -34,15 +34,15 @@ def check(text: str, file_path: str = "<rst-doc>") -> bool:
 
 def _check_file(file_path: str) -> ReturnCode:
     return_code = PASS
-    with open(file_path, "r", encoding="utf8", newline="\n") as f:
+    with open(file_path, encoding="utf8", newline="\n") as f:
         content = f.read()
         if not check(content, file_path):
             # print(f"No spaces between EN and CN chars detected at: {file_path}:{lineno}:\t{line}")
             return_code = FAIL
     return return_code
 
 
-def main(argv: Optional[Sequence[str]] = None) -> ReturnCode:
+def main(argv: Sequence[str] | None = None) -> ReturnCode:
     parser = argparse.ArgumentParser(prog="dochooks", description="pre-commit hooks for documentation")
     parser.add_argument("-v", "--version", action="version", version=__version__)
     parser.add_argument("filenames", nargs="*", help="Filenames to check")

dochooks/api_doc_checker/checkers/dead_link_checker.py

@@ -2,7 +2,6 @@
 
 import re
 from pathlib import Path
-from typing import Optional
 
 import docutils.nodes
 import httpx
@@ -15,7 +14,7 @@
 
 
 class DeadLinkChecker(Checker):
-    _links: list[tuple[Optional[int], str]] = []
+    _links: list[tuple[int | None, str]] = []
 
     def visit_reference(self, node: docutils.nodes.Element):
         uri = node.get("refuri")

dochooks/api_doc_checker/checkers/parameters_checker.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
 
 import re
-from typing import Optional
+from typing import Literal, TypedDict
 
 import docutils.nodes
 
-from ..._compat import Literal, TypedDict
 from ..utils import PATTERN_IDENTIFIER, is_valid_identifier
 from .checker import Checker, assert_is_element
 
@@ -14,11 +13,11 @@
 
 class APIParameter(TypedDict):
     name: str
-    type: Optional[str]
+    type: str | None
     is_rest: bool
     is_keyword: bool
     optional: bool
-    default: Optional[str]
+    default: str | None
 
 
 class ParametersChecker(Checker):
@@ -34,8 +33,8 @@ class ParametersChecker(Checker):
 
     _check_result = True
     _section_name_stack: list[str] = []
-    _api_type: Optional[APIType] = None
-    _api_name: Optional[str] = None
+    _api_type: APIType | None = None
+    _api_name: str | None = None
     _api_parameters: list[APIParameter]
 
     # TODO: 直接抽取函数声明来检查
@@ -82,7 +81,7 @@ def visit_section(self, node: docutils.nodes.Element):
     def depart_section(self, node: docutils.nodes.Element):
         self._section_name_stack.pop()
 
-    def _extract_parameter_info_from_list_item(self, node: docutils.nodes.Element) -> Optional[APIParameter]:
+    def _extract_parameter_info_from_list_item(self, node: docutils.nodes.Element) -> APIParameter | None:
         """对单行信息进行提取并检查"""
 
         doc_parameter: APIParameter = APIParameter(
@@ -203,10 +202,10 @@ def result(self) -> bool:
         return self._check_result
 
 
-def parse_api_name_and_parameters(api_declaration: str) -> tuple[Optional[str], list[APIParameter]]:
+def parse_api_name_and_parameters(api_declaration: str) -> tuple[str | None, list[APIParameter]]:
     """解析 API 声明的名称和参数"""
 
-    api_name: Optional[str] = None
+    api_name: str | None = None
     api_parameters: list[APIParameter] = []
 
     api_declaration = api_declaration.strip()

dochooks/api_doc_checker/core/roles.py

@@ -9,10 +9,9 @@
 - [The Docutils Document Tree](https://docutils.sourceforge.io/docs/ref/doctree.html)
 """
 
-
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from typing import TYPE_CHECKING, Any, Callable, Optional
 
 import docutils
 import docutils.nodes
@@ -112,18 +111,19 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 SPHINX_EXT_AUTODOC_ROLES: list[str] = []
 
-RoleFn = Callable[
-    [
-        str,
-        str,
-        str,
-        int,
-        docutils.parsers.rst.states.Inliner,
-        Optional[dict[str, Any]],
-        Optional[list[str]],
-    ],
-    tuple[list[Any], list[Any]],
-]
+if TYPE_CHECKING:
+    RoleFn = Callable[
+        [
+            str,
+            str,
+            str,
+            int,
+            docutils.parsers.rst.states.Inliner,
+            Optional[dict[str, Any]],  # type: ignore
+            Optional[list[str]],  # type: ignore
+        ],
+        tuple[list[Any], list[Any]],  # type: ignore
+    ]
 
 
 def _ignore_role(
@@ -132,8 +132,8 @@ def _ignore_role(
     text: str,
     lineno: int,
     inliner: docutils.parsers.rst.states.Inliner,
-    options: Optional[dict[str, Any]] = None,
-    content: Optional[list[str]] = None,
+    options: dict[str, Any] | None = None,
+    content: list[str] | None = None,
 ) -> tuple[list[Any], list[Any]]:
     """Stub for unknown roles."""
     print("name:", name)
@@ -159,8 +159,8 @@ def _custom_role(
         text: str,
         lineno: int,
         inliner: docutils.parsers.rst.states.Inliner,
-        options: Optional[dict[str, Any]] = None,
-        content: Optional[list[str]] = None,
+        options: dict[str, Any] | None = None,
+        content: list[str] | None = None,
     ) -> tuple[list[Any], list[Any]]:
         node = docutils.nodes.literal(
             rawsource=rawtext,

dochooks/insert_whitespace_between_cn_and_en_char/check.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import argparse
-from typing import Optional, Sequence
+from typing import Sequence
 
 from dochooks import __version__
 
@@ -17,15 +17,15 @@ def check(string: str) -> bool:
 
 def _check_file(file_path: str) -> ReturnCode:
     return_code = PASS
-    with open(file_path, "r", encoding="utf8", newline="\n") as f:
+    with open(file_path, encoding="utf8", newline="\n") as f:
         for lineno, line in enumerate(f, 1):
             if not check(line):
                 print(f"No spaces between EN and CN chars detected at: {file_path}:{lineno}:\t{line}")
                 return_code = FAIL
     return return_code
 
 
-def main(argv: Optional[Sequence[str]] = None) -> ReturnCode:
+def main(argv: Sequence[str] | None = None) -> ReturnCode:
     parser = argparse.ArgumentParser(prog="dochooks", description="pre-commit hooks for documentation")
     parser.add_argument("-v", "--version", action="version", version=__version__)
     parser.add_argument("filenames", nargs="*", help="Filenames to check")

dochooks/insert_whitespace_between_cn_and_en_char/format.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import argparse
-from typing import Optional, Sequence
+from typing import Sequence
 
 from dochooks import __version__
 
@@ -19,7 +19,7 @@ def format(text: str) -> str:
 def _format_file(file_path: str) -> ReturnCode:
     return_code = PASS
     formatted_text = ""
-    with open(file_path, "r", encoding="utf8", newline="\n") as f:
+    with open(file_path, encoding="utf8", newline="\n") as f:
         for lineno, line in enumerate(f, 1):
             if not check(line):
                 line = format(line)
@@ -32,7 +32,7 @@ def _format_file(file_path: str) -> ReturnCode:
     return return_code
 
 
-def main(argv: Optional[Sequence[str]] = None) -> ReturnCode:
+def main(argv: Sequence[str] | None = None) -> ReturnCode:
     parser = argparse.ArgumentParser(prog="dochooks", description="pre-commit hooks for documentation")
     parser.add_argument("-v", "--version", action="version", version=__version__)
     parser.add_argument("filenames", nargs="*", help="Filenames to check")

dochooks/insert_whitespace_between_cn_and_en_char/regex.py

@@ -1,9 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import Pattern
-
-from .._compat import Final
+from typing import Final, Pattern
 
 REGEX_CN_CHAR_STR: Final[str] = r"[\u4e00-\u9fa5]"
 REGEX_EN_CHAR_STR: Final[str] = r"[a-zA-Z0-9]"

pyproject.toml

@@ -27,6 +27,11 @@ check-whitespace-between-cn-and-en-char = "dochooks.insert_whitespace_between_cn
 insert-whitespace-between-cn-and-en-char = "dochooks.insert_whitespace_between_cn_and_en_char.format:main"
 api-doc-checker = "dochooks.api_doc_checker.check:main"
 
+[tool.pyright]
+include = ["dochooks", "tests"]
+pythonVersion = "3.8"
+typeCheckingMode = "strict"
+
 [tool.ruff]
 line-length = 120
 target-version = "py38"
@@ -44,8 +49,6 @@ select = [
   "UP",
   # Flake8-pyi
   "PYI",
-  # Flake8-use-pathlib
-  "PTH",
   # Yesqa
   "RUF100",
 ]

tests/test_api_doc_checker/test_checkers/test_parameters_checker.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import re
-from typing import Optional
 
 import pytest
 
@@ -107,9 +106,7 @@ def test_pattern_doc_parameter_type():
         ),
     ],
 )
-def test_parse_api_name_and_parameters(
-    api_declaration: str, api_name: Optional[str], api_parameters: list[APIParameter]
-):
+def test_parse_api_name_and_parameters(api_declaration: str, api_name: str | None, api_parameters: list[APIParameter]):
     api_name_actual, api_parameters_actual = parse_api_name_and_parameters(api_declaration)
     assert api_name == api_name_actual
     assert api_parameters == api_parameters_actual