Deprecate accessing and setting the doc attribute on nodes (#1434)

Co-authored-by: Marc Mueller <[email protected]>

Author: DanielNoord

ChangeLog

@@ -9,6 +9,10 @@ Release date: TBA
 * Add new (optional) ``doc_node`` attribute to ``nodes.Module``, ``nodes.ClassDef``,
   and ``nodes.FunctionDef``.
 
+* Accessing the ``doc`` attribute of ``nodes.Module``, ``nodes.ClassDef``, and
+  ``nodes.FunctionDef`` has been deprecated in favour of the ``doc_node`` attribute.
+  Note: ``doc_node`` is an (optional) ``nodes.Const`` whereas ``doc`` was an (optional) ``str``.
+
 * Replace custom ``cachedproperty`` with ``functools.cached_property`` and deprecate it
   for Python 3.8+.
 

astroid/nodes/scoped_nodes/scoped_nodes.py

@@ -438,7 +438,7 @@ class Module(LocalsDictNodeNG):
     def __init__(
         self,
         name: str,
-        doc: Optional[str],
+        doc: Optional[str] = None,
         file: Optional[str] = None,
         path: Optional[List[str]] = None,
         package: Optional[bool] = None,
@@ -463,7 +463,7 @@ def __init__(
         self.name = name
         """The name of the module."""
 
-        self.doc = doc
+        self._doc = doc
         """The module docstring."""
 
         self.file = file
@@ -509,6 +509,27 @@ def postinit(self, body=None, *, doc_node: Optional[Const] = None):
         """
         self.body = body
         self.doc_node = doc_node
+        if doc_node:
+            self._doc = doc_node.value
+
+    @property
+    def doc(self) -> Optional[str]:
+        """The module docstring."""
+        warnings.warn(
+            "The 'Module.doc' attribute is deprecated, "
+            "use 'Module.doc_node' instead.",
+            DeprecationWarning,
+        )
+        return self._doc
+
+    @doc.setter
+    def doc(self, value: Optional[str]) -> None:
+        warnings.warn(
+            "Setting the 'Module.doc' attribute is deprecated, "
+            "use 'Module.doc_node' instead.",
+            DeprecationWarning,
+        )
+        self._doc = value
 
     def _get_stream(self):
         if self.file_bytes is not None:
@@ -1515,7 +1536,7 @@ class FunctionDef(mixins.MultiLineBlockMixin, node_classes.Statement, Lambda):
     def __init__(
         self,
         name=None,
-        doc=None,
+        doc: Optional[str] = None,
         lineno=None,
         col_offset=None,
         parent=None,
@@ -1527,8 +1548,7 @@ def __init__(
         :param name: The name of the function.
         :type name: str or None
 
-        :param doc: The function's docstring.
-        :type doc: str or None
+        :param doc: The function docstring.
 
         :param lineno: The line that this node appears on in the source code.
         :type lineno: int or None
@@ -1553,11 +1573,8 @@ def __init__(
         :type name: str or None
         """
 
-        self.doc = doc
-        """The function's docstring.
-
-        :type doc: str or None
-        """
+        self._doc = doc
+        """The function docstring."""
 
         self.doc_node: Optional[Const] = None
         """The doc node associated with this node."""
@@ -1614,6 +1631,27 @@ def postinit(
         self.type_comment_args = type_comment_args
         self.position = position
         self.doc_node = doc_node
+        if doc_node:
+            self._doc = doc_node.value
+
+    @property
+    def doc(self) -> Optional[str]:
+        """The function docstring."""
+        warnings.warn(
+            "The 'FunctionDef.doc' attribute is deprecated, "
+            "use 'FunctionDef.doc_node' instead.",
+            DeprecationWarning,
+        )
+        return self._doc
+
+    @doc.setter
+    def doc(self, value: Optional[str]) -> None:
+        warnings.warn(
+            "Setting the 'FunctionDef.doc' attribute is deprecated, "
+            "use 'FunctionDef.doc_node' instead.",
+            DeprecationWarning,
+        )
+        self._doc = value
 
     @cached_property
     def extra_decorators(self) -> List[node_classes.Call]:
@@ -2164,7 +2202,7 @@ def my_meth(self, arg):
     def __init__(
         self,
         name=None,
-        doc=None,
+        doc: Optional[str] = None,
         lineno=None,
         col_offset=None,
         parent=None,
@@ -2176,8 +2214,7 @@ def __init__(
         :param name: The name of the class.
         :type name: str or None
 
-        :param doc: The function's docstring.
-        :type doc: str or None
+        :param doc: The class docstring.
 
         :param lineno: The line that this node appears on in the source code.
         :type lineno: int or None
@@ -2229,11 +2266,8 @@ def __init__(
         :type name: str or None
         """
 
-        self.doc = doc
-        """The class' docstring.
-
-        :type doc: str or None
-        """
+        self._doc = doc
+        """The class docstring."""
 
         self.doc_node: Optional[Const] = None
         """The doc node associated with this node."""
@@ -2254,6 +2288,25 @@ def __init__(
         for local_name, node in self.implicit_locals():
             self.add_local_node(node, local_name)
 
+    @property
+    def doc(self) -> Optional[str]:
+        """The class docstring."""
+        warnings.warn(
+            "The 'ClassDef.doc' attribute is deprecated, "
+            "use 'ClassDef.doc_node' instead.",
+            DeprecationWarning,
+        )
+        return self._doc
+
+    @doc.setter
+    def doc(self, value: Optional[str]) -> None:
+        warnings.warn(
+            "Setting the 'ClassDef.doc' attribute is deprecated, "
+            "use 'ClassDef.doc_node.value' instead.",
+            DeprecationWarning,
+        )
+        self._doc = value
+
     def implicit_parameters(self):
         return 1
 
@@ -2316,6 +2369,8 @@ def postinit(
             self._metaclass = metaclass
         self.position = position
         self.doc_node = doc_node
+        if doc_node:
+            self._doc = doc_node.value
 
     def _newstyle_impl(self, context=None):
         if context is None:

tests/unittest_builder.py

@@ -769,7 +769,11 @@ def test_module_base_props(self) -> None:
         """test base properties and method of an astroid module"""
         module = self.module
         self.assertEqual(module.name, "data.module")
-        self.assertEqual(module.doc, "test module for astroid\n")
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(module.doc, "test module for astroid\n")
+            assert len(records) == 1
+        assert isinstance(module.doc_node, nodes.Const)
+        self.assertEqual(module.doc_node.value, "test module for astroid\n")
         self.assertEqual(module.fromlineno, 0)
         self.assertIsNone(module.parent)
         self.assertEqual(module.frame(), module)
@@ -811,7 +815,11 @@ def test_function_base_props(self) -> None:
         module = self.module
         function = module["global_access"]
         self.assertEqual(function.name, "global_access")
-        self.assertEqual(function.doc, "function test")
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(function.doc, "function test")
+            assert len(records)
+        assert isinstance(function.doc_node, nodes.Const)
+        self.assertEqual(function.doc_node.value, "function test")
         self.assertEqual(function.fromlineno, 11)
         self.assertTrue(function.parent)
         self.assertEqual(function.frame(), function)
@@ -834,7 +842,11 @@ def test_class_base_props(self) -> None:
         module = self.module
         klass = module["YO"]
         self.assertEqual(klass.name, "YO")
-        self.assertEqual(klass.doc, "hehe\n    haha")
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(klass.doc, "hehe\n    haha")
+            assert len(records) == 1
+        assert isinstance(klass.doc_node, nodes.Const)
+        self.assertEqual(klass.doc_node.value, "hehe\n    haha")
         self.assertEqual(klass.fromlineno, 25)
         self.assertTrue(klass.parent)
         self.assertEqual(klass.frame(), klass)
@@ -888,7 +900,11 @@ def test_method_base_props(self) -> None:
         method = klass2["method"]
         self.assertEqual(method.name, "method")
         self.assertEqual([n.name for n in method.args.args], ["self"])
-        self.assertEqual(method.doc, "method\n        test")
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(method.doc, "method\n        test")
+            assert len(records) == 1
+        assert isinstance(method.doc_node, nodes.Const)
+        self.assertEqual(method.doc_node.value, "method\n        test")
         self.assertEqual(method.fromlineno, 48)
         self.assertEqual(method.type, "method")
         # class method

tests/unittest_nodes.py

@@ -1605,7 +1605,9 @@ def func():
     """
     )
     node: nodes.FunctionDef = astroid.extract_node(code)  # type: ignore[assignment]
-    assert node.doc == "Docstring"
+    with pytest.warns(DeprecationWarning) as records:
+        assert node.doc == "Docstring"
+        assert len(records) == 1
     assert isinstance(node.doc_node, nodes.Const)
     assert node.doc_node.value == "Docstring"
     assert node.doc_node.lineno == 2
@@ -1621,7 +1623,9 @@ def func():
     """
     )
     node = astroid.extract_node(code)
-    assert node.doc is None
+    with pytest.warns(DeprecationWarning) as records:
+        assert node.doc is None
+        assert len(records) == 1
     assert node.doc_node is None
 
 

tests/unittest_raw_building.py

@@ -17,6 +17,7 @@
 import unittest
 
 import _io
+import pytest
 
 from astroid.builder import AstroidBuilder
 from astroid.raw_building import (
@@ -44,12 +45,18 @@ def test_build_module(self) -> None:
     def test_build_class(self) -> None:
         node = build_class("MyClass")
         self.assertEqual(node.name, "MyClass")
-        self.assertEqual(node.doc, None)
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(node.doc, None)
+            assert len(records) == 1
+        self.assertEqual(node.doc_node, None)
 
     def test_build_function(self) -> None:
         node = build_function("MyFunction")
         self.assertEqual(node.name, "MyFunction")
-        self.assertEqual(node.doc, None)
+        with pytest.warns(DeprecationWarning) as records:
+            self.assertEqual(node.doc, None)
+            assert len(records) == 1
+        self.assertEqual(node.doc_node, None)
 
     def test_build_function_args(self) -> None:
         args = ["myArgs1", "myArgs2"]