Support property (#5)

* add support for property
* add documentation
* update message for missing attribute to include property

Author: jdkandersson

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [v1.0.3] - 2023-01-05
+
+### Added
+
+- Support for class properties
+
 ## [v1.0.2] - 2023-01-04
 
 ### Added
@@ -78,3 +84,4 @@
 [v1.0.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.0
 [v1.0.1]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.1
 [v1.0.2]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.2
+[v1.0.3]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.3

README.md

@@ -1315,6 +1315,16 @@ class FooClass:
     def __init__(self):
         self.bar = "bar"
 
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+    """
+
+    @property
+    def bar(self):
+        return "bar"
+
 class FooClass:
     """Perform foo action."""
 
@@ -1361,6 +1371,17 @@ class FooClass:
     def __init__(self):
         self.bar = "bar"
 
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+        bar: The value to perform the foo action on.
+    """
+
+    @property
+    def bar(self):
+        return "bar"
+
 class FooClass:
     """Perform foo action.
 

flake8_docstrings_complete/__init__.py

@@ -275,7 +275,7 @@ def _is_fixture_decorator(self, node: ast.expr) -> bool:
             node: The node to check.
 
         Returns:
-            Whether the node is a decorator fixture.
+            Whether the node is a fixture decorator.
         """
         # Handle variable
         fixture_name: str | None = None
@@ -298,17 +298,26 @@ def _is_fixture_decorator(self, node: ast.expr) -> bool:
     def _skip_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
         """Check whether to skip a function.
 
+        A function is skipped if it is a test function in a test file, if it is a fixture in a test
+        or fixture file or if it is a property.
+
         Args:
             node: The function to check
 
         Returns:
             Whether to skip the function.
         """
+        # Check for properties
+        if any(attrs.is_property_decorator(decorator) for decorator in node.decorator_list):
+            return True
+
+        # Check for test functions
         if self._file_type == types_.FileType.TEST and re.match(
             self._test_function_pattern, node.name
         ):
             return True
 
+        # Check for fixtures
         if self._file_type in {types_.FileType.TEST, types_.FileType.FIXTURE}:
             return any(self._is_fixture_decorator(decorator) for decorator in node.decorator_list)
 

flake8_docstrings_complete/attrs.py

@@ -26,7 +26,7 @@
 )
 ATTR_NOT_IN_DOCSTR_CODE = f"{ERROR_CODE_PREFIX}063"
 ATTR_NOT_IN_DOCSTR_MSG = (
-    f'{ATTR_NOT_IN_DOCSTR_CODE} "%s" attribute should be described in the docstring'
+    f'{ATTR_NOT_IN_DOCSTR_CODE} "%s" attribute/ property should be described in the docstring'
     f"{MORE_INFO_BASE}{ATTR_NOT_IN_DOCSTR_CODE.lower()}"
 )
 ATTR_IN_DOCSTR_CODE = f"{ERROR_CODE_PREFIX}064"
@@ -39,6 +39,25 @@
 PRIVATE_ATTR_PREFIX = "_"
 
 
+def is_property_decorator(node: ast.expr) -> bool:
+    """Determine whether an expression is a property decorator.
+
+    Args:
+        node: The node to check.
+
+    Returns:
+        Whether the node is a property decorator.
+    """
+    if isinstance(node, ast.Name):
+        return node.id == "property"
+
+    # Handle call
+    if isinstance(node, ast.Call):
+        return is_property_decorator(node=node.func)
+
+    return False
+
+
 def _get_class_target_name(target: ast.expr) -> ast.Name | None:
     """Get the name of the target for an assignment on the class.
 
@@ -61,7 +80,7 @@ def _get_class_target_name(target: ast.expr) -> ast.Name | None:
 
 
 def _iter_class_attrs(
-    nodes: Iterable[ast.Assign | ast.AnnAssign | ast.AugAssign],
+    nodes: Iterable[ast.Assign | ast.AnnAssign | ast.AugAssign | types_.Node],
 ) -> Iterator[types_.Node]:
     """Get the node of the variable being assigned at the class level if the target is a Name.
 
@@ -72,7 +91,9 @@ def _iter_class_attrs(
         All the nodes of name targets of the assignment expressions.
     """
     for node in nodes:
-        if isinstance(node, ast.Assign):
+        if isinstance(node, types_.Node):
+            yield node
+        elif isinstance(node, ast.Assign):
             target_names = filter(
                 None, (_get_class_target_name(target) for target in node.targets)
             )
@@ -136,7 +157,7 @@ def _iter_method_attrs(
 def check(
     docstr_info: docstring.Docstring,
     docstr_node: ast.Constant,
-    class_assign_nodes: Iterable[ast.Assign | ast.AnnAssign | ast.AugAssign],
+    class_assign_nodes: Iterable[ast.Assign | ast.AnnAssign | ast.AugAssign | types_.Node],
     method_assign_nodes: Iterable[ast.Assign | ast.AnnAssign | ast.AugAssign],
 ) -> Iterator[types_.Problem]:
     """Check that all class attributes are described in the docstring.
@@ -211,7 +232,7 @@ class VisitorWithinClass(ast.NodeVisitor):
         method_assign_nodes: All the return nodes encountered within the class methods.
     """
 
-    class_assign_nodes: list[ast.Assign | ast.AnnAssign | ast.AugAssign]
+    class_assign_nodes: list[ast.Assign | ast.AnnAssign | ast.AugAssign | types_.Node]
     method_assign_nodes: list[ast.Assign | ast.AnnAssign | ast.AugAssign]
     _visited_once: bool
     _visited_top_level: bool
@@ -237,6 +258,18 @@ def visit_assign(self, node: ast.Assign | ast.AnnAssign | ast.AugAssign) -> None
         # Ensure recursion continues
         self.generic_visit(node)
 
+    def visit_any_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        """Visit a function definition node.
+
+        Args:
+            node: The function definition to check.
+        """
+        if any(is_property_decorator(decorator) for decorator in node.decorator_list):
+            self.class_assign_nodes.append(
+                types_.Node(lineno=node.lineno, col_offset=node.col_offset, name=node.name)
+            )
+        self.visit_top_level(node=node)
+
     def visit_once(self, node: ast.AST) -> None:
         """Visit the node once and then skip.
 
@@ -264,6 +297,6 @@ def visit_top_level(self, node: ast.AST) -> None:
     visit_AnnAssign = visit_assign  # noqa: N815,DCO063
     visit_AugAssign = visit_assign  # noqa: N815,DCO063
     # Ensure that nested functions and classes are not iterated over
-    visit_FunctionDef = visit_top_level  # noqa: N815,DCO063
-    visit_AsyncFunctionDef = visit_top_level  # noqa: N815,DCO063
+    visit_FunctionDef = visit_any_function  # noqa: N815,DCO063
+    visit_AsyncFunctionDef = visit_any_function  # noqa: N815,DCO063
     visit_ClassDef = visit_once  # noqa: N815,DCO063

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "flake8-docstrings-complete"
-version = "1.0.2"
+version = "1.0.3"
 description = "A linter that checks docstrings are complete"
 authors = ["David Andersson <david@jdkandersson.com>"]
 license = "Apache 2.0"

tests/unit/test___init__.py

@@ -550,6 +550,54 @@ def function_1(self):
         ),
         pytest.param(
             '''
+class Class1:
+    """Docstring.
+
+    Attrs:
+        function_1:
+    """
+    @property
+    def function_1(self):
+        """Docstring 1."""
+        return 1
+''',
+            (),
+            id="property return value docstring no returns section",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring.
+
+    Attrs:
+        function_1:
+    """
+    @property
+    async def function_1(self):
+        """Docstring 1."""
+        return 1
+''',
+            (),
+            id="async property return value docstring no returns section",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring.
+
+    Attrs:
+        function_1:
+    """
+    @property()
+    def function_1(self):
+        """Docstring 1."""
+        return 1
+''',
+            (),
+            id="property call return value docstring no returns section",
+        ),
+        pytest.param(
+            '''
 def function_1():
     """Docstring 1."""
     yield
@@ -647,6 +695,22 @@ def function_1(self):
             (),
             id="method yield value docstring yields section",
         ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring.
+
+    Attrs:
+        function_1:
+    """
+    @property
+    def function_1(self):
+        """Docstring 1."""
+        yield 1
+''',
+            (),
+            id="property yield value docstring no yields section",
+        ),
     ],
 )
 def test_plugin(code: str, expected_result: tuple[str, ...]):

tests/unit/test___init__attrs.py

@@ -186,6 +186,70 @@ class Class1:
 class Class1:
     """Docstring 1.
 
+    Attrs:
+    """
+    @property
+    def attr_1():
+        """Docstring 2."""
+        return "value 1"
+''',
+            (f"8:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_1'}",),
+            id="class has single property docstring no attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
+    Attrs:
+    """
+    @property
+    def attr_1(self):
+        """Docstring 2."""
+        self.attr_2 = "value 2"
+        return "value 1"
+''',
+            (
+                f"8:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_1'}",
+                f"10:8 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_2'}",
+            ),
+            id="class has single property with assignment docstring no attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
+    Attrs:
+    """
+    @property
+    async def attr_1():
+        """Docstring 2."""
+        return "value 1"
+''',
+            (f"8:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_1'}",),
+            id="class has single async property docstring no attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
+    Attrs:
+    """
+    @property()
+    def attr_1():
+        """Docstring 2."""
+        return "value 1"
+''',
+            (f"8:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_1'}",),
+            id="class has single property call docstring no attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
     Attrs:
     """
     def __init__(self):
@@ -273,6 +337,28 @@ def method_1(self):
 class Class1:
     """Docstring 1.
 
+    Attrs:
+    """
+    @property
+    def attr_1():
+        """Docstring 2."""
+        return "value 1"
+    @property
+    def attr_2():
+        """Docstring 3."""
+        return "value 3"
+''',
+            (
+                f"8:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_1'}",
+                f"12:4 {ATTR_NOT_IN_DOCSTR_MSG % 'attr_2'}",
+            ),
+            id="class has multiple property docstring no attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
     Attrs:
     """
     def method_1(self):
@@ -541,6 +627,22 @@ class Class1:
 class Class1:
     """Docstring 1.
 
+    Attrs:
+        attr_1:
+    """
+    @property
+    def attr_1():
+        """Docstring 2."""
+        return "value 1"
+''',
+            (),
+            id="class single property docstring single attr",
+        ),
+        pytest.param(
+            '''
+class Class1:
+    """Docstring 1.
+
     Attrs:
         attr_1:
     """