drop python 3.9 and add doc

Author: eggplants

deepl/__init__.py

@@ -1,4 +1,4 @@
-""".. include:: ../README.md"""
+""".. include:: ../README.md"""  # noqa: D415
 
 import importlib.metadata
 

deepl/deepl.py

@@ -1,41 +1,40 @@
-from __future__ import annotations
+"""Translate text using DeepL with Playwright."""
 
 import asyncio
 import contextlib
 import os
+from collections.abc import Coroutine
 from functools import partial
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import Any, ClassVar
 from urllib.parse import quote
 
 from install_playwright import install
 from playwright._impl._errors import Error as PlaywrightError
 from playwright.async_api import async_playwright
-
-if TYPE_CHECKING:
-    from collections.abc import Coroutine
-
-    from playwright.async_api._generated import Browser, Playwright
+from playwright.async_api._generated import Browser, Playwright
 
 
 class DeepLCLIError(Exception):
-    pass
+    """Generic error for DeepLCLI."""
 
 
 class DeepLCLIPageLoadError(Exception):
-    pass
+    """Page load error for DeepLCLI."""
 
 
 class DeepLCLI:
-    """
+    """Translate text using DeepL with Playwright.
+
     How to get language list:
+
     1. open language dropdown
     2. run on console:
 
     ```
     // const fr =
     // cost to =
     Array.from(
-      document.querySelectorAll(`button[data-testid^='translator-lang-option']`)
+        document.querySelectorAll(`button[data-testid^='translator-lang-option']`)
     ).map(e=>e.getAttribute('data-testid').split('translator-lang-option-')[1].toLowerCase())
     // new Set(fr).difference(new Set(to))
     // new Set(to).difference(new Set(fr))
@@ -90,6 +89,17 @@ def __init__(
         *,
         use_dom_submit: bool = False,
     ) -> None:
+        """Initialize DeepLCLI.
+
+        Args:
+            fr_lang (str): Source language.
+            to_lang (str): Target language.
+            timeout (int): Timeout in milliseconds. Default is 15000ms.
+            use_dom_submit (bool): Use DOM submit instead of URL. Default is False.
+
+        Raises:
+            DeepLCLIError: If the language is not valid.
+        """
         if fr_lang not in self.fr_langs:
             raise DeepLCLIError(
                 f"{fr_lang!r} is not valid language. Valid language:\n" + repr(self.fr_langs),
@@ -108,13 +118,37 @@ def __init__(
         self.use_dom_submit = use_dom_submit
 
     def translate(self, script: str) -> str:
+        """Translate script.
+
+        Args:
+            script (str): Script to translate.
+
+        Returns:
+            str: Translated script.
+
+        Raises:
+            DeepLCLIError: If the script is empty or too long.
+            DeepLCLIPageLoadError: If the page load fails.
+        """
         script = self.__sanitize_script(script)
 
         # run in the current thread
         loop = asyncio.get_event_loop()
         return loop.run_until_complete(self.__translate(script))
 
     def translate_async(self, script: str) -> Coroutine[Any, Any, str]:
+        """Translate script asynchronously.
+
+        Args:
+            script (str): Script to translate.
+
+        Returns:
+            Coroutine[Any, Any, str]: Translated script.
+
+        Raises:
+            DeepLCLIError: If the script is empty or too long.
+            DeepLCLIPageLoadError: If the page load fails.
+        """
         script = self.__sanitize_script(script)
 
         return self.__translate(script)

deepl/main.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
+"""Main module of deepl CLI."""
 
 import argparse
 import sys
@@ -14,12 +14,23 @@
 
 
 class DeepLCLIFormatter(
-    argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter,
+    argparse.ArgumentDefaultsHelpFormatter,
+    argparse.RawDescriptionHelpFormatter,
 ):
-    pass
+    """Custom help formatter for argparse."""
 
 
 def check_file(v: str) -> str:
+    """Check if the file is a text file.
+
+    Args:
+        v (str): file path
+    Returns:
+        str: file path
+    Raises:
+        argparse.ArgumentTypeError: if the file is not a text file
+    """
+
     def is_binary_string(b: bytes) -> bool:
         chars = bytearray({7, 8, 9, 10, 12, 13, 27} | set(range(0x20, 0x100)) - {0x7F})
         return bool(b.translate(None, chars))
@@ -37,6 +48,15 @@ def is_binary_string(b: bytes) -> bool:
 
 
 def check_natural(v: str) -> int:
+    """Check if the value is a natural number.
+
+    Args:
+        v (str): value to check
+    Returns:
+        int: value
+    Raises:
+        argparse.ArgumentTypeError: if the value is not a natural number
+    """
     n = int(v)
     if n < 0:
         msg = f"{v} must not be negative."
@@ -46,26 +66,50 @@ def check_natural(v: str) -> int:
 
 
 def check_input_lang(lang: str) -> str:
+    """Check if the input language is valid.
+
+    Args:
+        lang (str): input language
+    Returns:
+        str: input language
+    Raises:
+        argparse.ArgumentTypeError: if the input language is not valid
+    """
     if lang not in DeepLCLI.fr_langs:
         raise argparse.ArgumentTypeError(
-            f"{lang!r} is not valid language. Valid language:\n"
-            + repr(DeepLCLI.fr_langs),
+            f"{lang!r} is not valid language. Valid language:\n" + repr(DeepLCLI.fr_langs),
         )
 
     return lang
 
 
 def check_output_lang(lang: str) -> str:
+    """Check if the output language is valid.
+
+    Args:
+        lang (str): output language
+    Returns:
+        str: output language
+    Raises:
+        argparse.ArgumentTypeError: if the output language is not valid
+    """
     if lang not in DeepLCLI.to_langs:
         raise argparse.ArgumentTypeError(
-            f"{lang!r} is not valid language. Valid language:\n"
-            + repr(DeepLCLI.to_langs),
+            f"{lang!r} is not valid language. Valid language:\n" + repr(DeepLCLI.to_langs),
         )
     return lang
 
 
 def parse_args(test: str | None = None) -> argparse.Namespace:
-    """Parse arguments."""
+    """Parse arguments.
+
+    Args:
+        test (str | None): test string
+    Returns:
+        argparse.Namespace: parsed arguments
+    Raises:
+        argparse.ArgumentTypeError: if the arguments are not valid
+    """
     parser = argparse.ArgumentParser(
         prog="deepl",
         formatter_class=(
@@ -98,10 +142,18 @@ def parse_args(test: str | None = None) -> argparse.Namespace:
         help="read source text from stdin",
     )
     parser.add_argument(
-        "-F", "--fr", type=check_input_lang, help="input language", required=True,
+        "-F",
+        "--fr",
+        type=check_input_lang,
+        help="input language",
+        required=True,
     )
     parser.add_argument(
-        "-T", "--to", type=check_output_lang, help="output language", required=True,
+        "-T",
+        "--to",
+        type=check_output_lang,
+        help="output language",
+        required=True,
     )
     parser.add_argument(
         "-t",
@@ -118,7 +170,10 @@ def parse_args(test: str | None = None) -> argparse.Namespace:
         help="make output verbose",
     )
     parser.add_argument(
-        "-V", "--version", action="version", version=f"%(prog)s {__version__}",
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
     )
 
     if test is None:
@@ -127,6 +182,11 @@ def parse_args(test: str | None = None) -> argparse.Namespace:
 
 
 def main(test: str | None = None) -> None:
+    """Main function.
+
+    Args:
+        test (str | None): test string
+    """
     args = parse_args(test)
     t = DeepLCLI(args.fr, args.to, timeout=args.timeout)
     script = ""

examples/async.py

@@ -7,7 +7,7 @@
 
 
 def print_translated_text(future: asyncio.Future[str]) -> None:
-    """receive the result of async func and print."""
+    """Receive the result of async func and print."""
     try:
         translated_text = future.result()
         print(translated_text)
@@ -19,13 +19,13 @@ def print_translated_text(future: asyncio.Future[str]) -> None:
 
 
 async def translate(text: str) -> str:
-    """translate asynchronously."""
+    """Translate asynchronously."""
     t = DeepLCLI("en", "ja")
     return await t.translate_async(text)
 
 
 async def do_something() -> None:
-    """do something asynchronously."""
+    """Do something asynchronously."""
     await asyncio.sleep(10)
     print("Another task done!")
 

pyproject.toml

@@ -13,11 +13,10 @@ keywords = [
 ]
 license = { text = "MIT" }
 authors = [ { name = "eggplants", email = "w10776e8w@yahoo.co.jp" } ]
-requires-python = ">=3.9,<4"
+requires-python = ">=3.10,<4"
 classifiers = [
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -36,7 +35,7 @@ scripts.deepl = "deepl.main:main"
 
 [dependency-groups]
 dev = [
-  "mypy>=0.991,<1.15",
+  "mypy>=1,<1.15",
   "pre-commit>=2.20,<4",
   "pytest>=7.2.2,<9",
   "pytest-asyncio>=0.21,<0.25",
@@ -63,24 +62,23 @@ format.quote-style = "double"
 lint.select = [
   "ALL",
 ]
-lint.ignore = [
-  "D",
-]
 lint.per-file-ignores."examples/*.py" = [
+  "D",
   "INP001", # Add an __init__.py.
   "T201",   # `print` found
 ]
 lint.per-file-ignores."main.py" = [
   "T201", # `print` found
 ]
-lint.per-file-ignores."tests/test_*.py" = [
+lint.per-file-ignores."tests/*.py" = [
+  "D",
   "S101", # Use of assert detected
 ]
 lint.pydocstyle.convention = "google"
 
 [tool.mypy]
 pretty = true
-python_version = "3.9"
+python_version = "3.10"
 show_error_codes = true
 strict = true