refactor: General maintenance

Author: pawamoy

config/pytest.ini

@@ -12,3 +12,5 @@ filterwarnings =
   error
   # TODO: remove once pytest-xdist 4 is released
   ignore:.*rsyncdir:DeprecationWarning:xdist
+  ignore:.*Field:UserWarning:pydantic
+  ignore:.*:DeprecationWarning

config/ruff.toml

@@ -59,6 +59,7 @@ ignore = [
 ]
 "tests/*.py" = [
     "ARG005",  # Unused lambda argument
+    "D103",  # Missing docstring in public function
     "FBT001",  # Boolean positional arg in function definition
     "PLR2004",  # Magic value used in comparison
     "S101",  # Use of assert detected

pyproject.toml

@@ -87,6 +87,10 @@ dev-dependencies = [
     "twine>=5.0; python_version < '3.13'",
 
     # ci
+    "docstring-parser>=0.7",
+    "django>=3.2",
+    "marshmallow>=3.13",
+    "pydantic>=1.8",
     "duty>=1.4",
     "ruff>=0.4",
     "pytest>=8.2",

scripts/get_annotations.py

@@ -10,18 +10,17 @@
 from typing import List
 
 try:
-    from ast import unparse  # type: ignore
+    from ast import unparse  # type: ignore[attr-defined]
 except ImportError:
-    from astunparse import unparse as _unparse
+    from astunparse import unparse as _unparse  # type: ignore[no-redef]
 
-    unparse = lambda node: _unparse(node).rstrip("\n").replace("(", "").replace(")", "")
+    unparse = lambda node: _unparse(node).rstrip("\n").replace("(", "").replace(")", "")  # type: ignore[assignment]  # noqa: E731
 
 regex = re.compile(r"\w+")
 
 
 def scan_file(filepath: str) -> set:
-    """
-    Scan a Python file and return a set of annotations.
+    """Scan a Python file and return a set of annotations.
 
     Since parsing `Optional[typing.List]` and `Optional[typing.Dict]` is the same,
     we're not interested in keeping the actual names.
@@ -41,21 +40,20 @@ def scan_file(filepath: str) -> set:
     path = Path(filepath)
     try:
         code = ast.parse(path.read_text())
-    except:
+    except:  # noqa: E722
         return annotations
     for node in ast.walk(code):
         if hasattr(node, "annotation"):
             try:
-                unparsed = unparse(node.annotation)  # type: ignore
+                unparsed = unparse(node.annotation)
                 annotations.add(regex.sub("a", unparsed))
-            except:
+            except:  # noqa: E722, S112
                 continue
     return annotations
 
 
 def main(directories: List[str]) -> int:
-    """
-    Scan Python files in a list of directories.
+    """Scan Python files in a list of directories.
 
     First, all the files are stored in a list,
     then the scanning is done in parallel with a multiprocessing pool.
@@ -71,7 +69,6 @@ def main(directories: List[str]) -> int:
     all_files = []
     for directory in directories:
         all_files.extend(glob.glob(directory.rstrip("/") + "/**/*.py", recursive=True))
-    n_files = len(all_files)
     with Pool(cpu_count() - 1) as pool:
         sets = pool.map(scan_file, all_files)
     annotations: set = set().union(*sets)

src/pytkdocs/cli.py

@@ -19,14 +19,14 @@
 import traceback
 from contextlib import contextmanager
 from io import StringIO
-from typing import Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Iterator
 
+from pytkdocs import debug
 from pytkdocs.loader import Loader
-from pytkdocs.objects import Object
 from pytkdocs.serializer import serialize_object
 
-
-from pytkdocs import debug
+if TYPE_CHECKING:
+    from pytkdocs.objects import Object
 
 
 class _DebugInfo(argparse.Action):
@@ -39,16 +39,15 @@ def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
 
 
 def process_config(config: dict) -> dict:
-    """
-    Process a loading configuration.
+    """Process a loading configuration.
 
     The `config` argument is a dictionary looking like this:
 
     ```python
     {
         "objects": [
             {"path": "python.dotted.path.to.the.object1"},
-            {"path": "python.dotted.path.to.the.object2"}
+            {"path": "python.dotted.path.to.the.object2"},
         ]
     }
     ```
@@ -69,7 +68,7 @@ def process_config(config: dict) -> dict:
             "path.to.object2": [
                 "message1",
                 "message2",
-            ]
+            ],
         },
         "objects": [
             {
@@ -80,7 +79,7 @@ def process_config(config: dict) -> dict:
                 "path": "path.to.object2",
                 # other attributes, see the documentation for `pytkdocs.objects` or `pytkdocs.serializer`
             },
-        ]
+        ],
     }
     ```
 
@@ -114,8 +113,7 @@ def process_config(config: dict) -> dict:
 
 
 def process_json(json_input: str) -> dict:
-    """
-    Process JSON input.
+    """Process JSON input.
 
     Simply load the JSON as a Python dictionary, then pass it to [`process_config`][pytkdocs.cli.process_config].
 
@@ -129,39 +127,36 @@ def process_json(json_input: str) -> dict:
 
 
 def extract_docstring_parsing_errors(errors: dict, obj: Object) -> None:
-    """
-    Recursion helper.
+    """Recursion helper.
 
     Update the `errors` dictionary by side-effect. Recurse on the object's children.
 
     Arguments:
         errors: The dictionary to update.
         obj: The object.
     """
-    if hasattr(obj, "docstring_errors") and obj.docstring_errors:  # noqa: WPS421 (hasattr)
+    if hasattr(obj, "docstring_errors") and obj.docstring_errors:
         errors[obj.path] = obj.docstring_errors
     for child in obj.children:
         extract_docstring_parsing_errors(errors, child)
 
 
 def extract_errors(obj: Object) -> dict:
-    """
-    Extract the docstring parsing errors of each object, recursively, into a flat dictionary.
+    """Extract the docstring parsing errors of each object, recursively, into a flat dictionary.
 
     Arguments:
         obj: An object from `pytkdocs.objects`.
 
     Returns:
         A flat dictionary. Keys are the objects' names.
     """
-    parsing_errors: Dict[str, List[str]] = {}
+    parsing_errors: dict[str, list[str]] = {}
     extract_docstring_parsing_errors(parsing_errors, obj)
     return parsing_errors
 
 
 def get_parser() -> argparse.ArgumentParser:
-    """
-    Return the program argument parser.
+    """Return the program argument parser.
 
     Returns:
         The argument parser for the program.
@@ -180,9 +175,8 @@ def get_parser() -> argparse.ArgumentParser:
 
 
 @contextmanager
-def discarded_stdout():
-    """
-    Discard standard output.
+def discarded_stdout() -> Iterator[None]:
+    """Discard standard output.
 
     Yields:
         Nothing: We only yield to act as a context manager.
@@ -218,14 +212,14 @@ def main(args: list[str] | None = None) -> int:
             with discarded_stdout():
                 try:
                     output = json.dumps(process_json(line))
-                except Exception as error:  # noqa: W0703 (we purposely catch everything)
+                except Exception as error:  # noqa: BLE001
                     # Don't fail on error. We must handle the next inputs.
                     # Instead, print error as JSON.
                     output = json.dumps({"error": str(error), "traceback": traceback.format_exc()})
-            print(output)  # noqa: WPS421 (we need to print at some point)
+            print(output)
     else:
         with discarded_stdout():
             output = json.dumps(process_json(sys.stdin.read()))
-        print(output)  # noqa: WPS421 (we need to print at some point)
+        print(output)
 
     return 0