add support for typing.overload (#22)

* add support for typing.overload

Author: jdkandersson

.vscode/settings.json

@@ -1,6 +1,3 @@
 {
   "python.analysis.typeCheckingMode": "basic",
-  "python.linting.pylintEnabled": true,
-  "python.linting.enabled": true,
-  "python.formatting.provider": "black"
 }

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [v1.3.0] - 2023-11-29
+
+### Added
+
+- Support for `typing.overload`.
+
 ## [v1.2.0] - 2023-07-12
 
 ### Added
@@ -110,3 +116,4 @@
 [v1.0.4]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.4
 [v1.1.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.1.0
 [v1.2.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.2.0
+[v1.3.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.3.0

flake8_docstrings_complete/__init__.py

@@ -295,6 +295,30 @@ def _is_fixture_decorator(self, node: ast.expr) -> bool:
         # No valid syntax can reach here
         return False  # pragma: nocover
 
+    def _is_overload_decorator(self, node: ast.expr) -> bool:
+        """Determine whether an expression is an overload decorator.
+
+        Args:
+            node: The node to check.
+
+        Returns:
+            Whether the node is an overload decorator.
+        """
+        if isinstance(node, ast.Name):
+            return node.id == "overload"
+
+        # Handle call
+        if isinstance(node, ast.Call):
+            return self._is_overload_decorator(node=node.func)
+
+        # Handle attr
+        if isinstance(node, ast.Attribute):
+            value = node.value
+            return node.attr == "overload" and isinstance(value, ast.Name) and value.id == "typing"
+
+        # There is no valid syntax that gets to here
+        return False  # pragma: nocover
+
     def _skip_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
         """Check whether to skip a function.
 
@@ -321,6 +345,10 @@ def _skip_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
         if self._file_type in {types_.FileType.TEST, types_.FileType.FIXTURE}:
             return any(self._is_fixture_decorator(decorator) for decorator in node.decorator_list)
 
+        # Check for overload
+        if any(self._is_overload_decorator(decorator) for decorator in node.decorator_list):
+            return True
+
         return False
 
     def visit_any_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:

flake8_docstrings_complete/attrs.py

@@ -1,4 +1,4 @@
-"""The arguments section checks."""
+"""The attributes section checks."""
 
 from __future__ import annotations
 

pyproject.toml

@@ -1,18 +1,19 @@
 [tool.poetry]
 name = "flake8-docstrings-complete"
-version = "1.2.0"
+version = "1.3.0"
 description = "A linter that checks docstrings are complete"
 authors = ["David Andersson <david@jdkandersson.com>"]
 license = "Apache 2.0"
 readme = "README.md"
-packages = [{include = "flake8_docstrings_complete"}]
+packages = [{ include = "flake8_docstrings_complete" }]
 classifiers = [
     "Framework :: Flake8",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.9",
@@ -57,9 +58,5 @@ module = "tests.*"
 disallow_untyped_defs = false
 
 [tool.pylint.messages_control]
-enable = [
-    "useless-suppression"
-]
-disable = [
-    "wrong-import-position"
-]
+enable = ["useless-suppression"]
+disable = ["wrong-import-position"]

tests/unit/test___init__.py

@@ -31,6 +31,33 @@ def function_1():
         ),
         pytest.param(
             """
+@overload
+def function_1():
+    ...
+""",
+            (),
+            id="function docstring missing overload",
+        ),
+        pytest.param(
+            """
+@overload()
+def function_1():
+    ...
+""",
+            (),
+            id="function docstring missing overload call",
+        ),
+        pytest.param(
+            """
+@typing.overload
+def function_1():
+    ...
+""",
+            (),
+            id="function docstring missing overload attr",
+        ),
+        pytest.param(
+            """
 def function_1():
     return