👷 ci: use ruff and update ci workflow

.github/workflows/lint-and-fmt.yml

@@ -0,0 +1,52 @@
+name: Lint and Format
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+
+jobs:
+  lint-and-fmt:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Only run linter and formatter on minimum supported Python version
+        python-version: ["3.8"]
+        architecture: ["x64"]
+    name: lint and fmt - Python ${{ matrix.python-version }} on ${{ matrix.architecture }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install prettier
+        run: |
+          npm install -g prettier
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Install python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: ${{ matrix.architecture }}
+          cache: "poetry"
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: |
+          just ci-install
+
+      - name: lint
+        run: |
+          just ci-lint
+
+      - name: format check
+        run: |
+          just ci-fmt-check

.github/workflows/unit-test.yml

@@ -1,15 +1,20 @@
 name: Unit Test
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+  workflow_dispatch:
 
 jobs:
   unit-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12-dev"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         architecture: ["x64"]
-    name: Python ${{ matrix.python-version }} on ${{ matrix.architecture }} test
+    name: unittest - Python ${{ matrix.python-version }} on ${{ matrix.architecture }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -24,11 +29,15 @@ jobs:
           architecture: ${{ matrix.architecture }}
           cache: "poetry"
 
+      - name: Install just
+        uses: extractions/setup-just@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Install dependencies
-        if: steps.poetry-cache.outputs.cache-hit != 'true'
         run: |
-          poetry install -E rst-parser
+          just ci-install
 
       - name: unit test
         run: |
-          poetry run pytest
+          just ci-test

.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]"