Remove deprecated doc attribute (#2154)

ChangeLog

@@ -121,13 +121,18 @@ Release date: TBA
 
   Refs #2141
 
+* Remove deprecated ``Ellipsis``, ``ExtSlice``, ``Index`` nodes.
+
+  Refs #2152
+
 * Remove deprecated ``is_sys_guard`` and ``is_typing_guard`` methods.
 
   Refs #2153
 
-* Remove deprecated ``Ellipsis``, ``ExtSlice``, ``Index`` nodes.
+* Remove deprecated ``doc`` attribute for ``Module``, ``ClassDef``, and ``FunctionDef``.
+  Use the ``doc_node`` attribute instead.
 
-  Refs #2152
+  Refs #2154
 
 
 What's New in astroid 2.15.5?

astroid/nodes/scoped_nodes/scoped_nodes.py

@@ -201,7 +201,6 @@ class Module(LocalsDictNodeNG):
 
     _other_fields = (
         "name",
-        "doc",
         "file",
         "path",
         "package",
@@ -221,9 +220,6 @@ def __init__(
         self.name = name
         """The name of the module."""
 
-        self._doc: str | None = None
-        """The module docstring."""
-
         self.file = file
         """The path to the file that this ast has been extracted from.
 
@@ -262,29 +258,6 @@ def postinit(
     ):
         self.body = body
         self.doc_node = doc_node
-        if doc_node:
-            self._doc = doc_node.value
-
-    @property
-    def doc(self) -> str | None:
-        """The module docstring."""
-        warnings.warn(
-            "The 'Module.doc' attribute is deprecated, "
-            "use 'Module.doc_node' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self._doc
-
-    @doc.setter
-    def doc(self, value: str | None) -> None:
-        warnings.warn(
-            "Setting the 'Module.doc' attribute is deprecated, "
-            "use 'Module.doc_node' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self._doc = value
 
     def _get_stream(self):
         if self.file_bytes is not None:
@@ -1115,7 +1088,7 @@ class FunctionDef(
     type_comment_returns = None
     """If present, this will contain the return type annotation, passed by a type comment"""
     # attributes below are set by the builder module or by raw factories
-    _other_fields = ("name", "doc", "position")
+    _other_fields = ("name", "position")
     _other_other_fields = (
         "locals",
         "_type",
@@ -1144,9 +1117,6 @@ def __init__(
         self.name = name
         """The name of the function."""
 
-        self._doc: str | None = None
-        """DEPRECATED: The function docstring."""
-
         self.locals = {}
         """A map of the name of a local variable to the node defining it."""
 
@@ -1203,29 +1173,6 @@ 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) -> str | None:
-        """The function docstring."""
-        warnings.warn(
-            "The 'FunctionDef.doc' attribute is deprecated, "
-            "use 'FunctionDef.doc_node' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self._doc
-
-    @doc.setter
-    def doc(self, value: str | None) -> None:
-        warnings.warn(
-            "Setting the 'FunctionDef.doc' attribute is deprecated, "
-            "use 'FunctionDef.doc_node' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self._doc = value
 
     @cached_property
     def extra_decorators(self) -> list[node_classes.Call]:
@@ -1850,7 +1797,7 @@ def my_meth(self, arg):
             ":type: str"
         ),
     )
-    _other_fields = ("name", "doc", "is_dataclass", "position")
+    _other_fields = ("name", "is_dataclass", "position")
     _other_other_fields = ("locals", "_newstyle")
     _newstyle: bool | None = None
 
@@ -1886,9 +1833,6 @@ def __init__(
         self.decorators = None
         """The decorators that are applied to this class."""
 
-        self._doc: str | None = None
-        """DEPRECATED: The class docstring."""
-
         self.doc_node: Const | None = None
         """The doc node associated with this node."""
 
@@ -1910,27 +1854,6 @@ def __init__(
 
     infer_binary_op: ClassVar[InferBinaryOp[ClassDef]]
 
-    @property
-    def doc(self) -> str | None:
-        """The class docstring."""
-        warnings.warn(
-            "The 'ClassDef.doc' attribute is deprecated, "
-            "use 'ClassDef.doc_node' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self._doc
-
-    @doc.setter
-    def doc(self, value: str | None) -> None:
-        warnings.warn(
-            "Setting the 'ClassDef.doc' attribute is deprecated, "
-            "use 'ClassDef.doc_node.value' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self._doc = value
-
     def implicit_parameters(self) -> Literal[1]:
         return 1
 
@@ -1967,8 +1890,6 @@ 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: InferenceContext | None = None):
         if context is None:

tests/brain/test_brain.py

@@ -1777,9 +1777,6 @@ def test(a, b):
         assert isinstance(partial, objects.PartialFunction)
         assert isinstance(partial.doc_node, nodes.Const)
         assert partial.doc_node.value == "Docstring"
-        with pytest.warns(DeprecationWarning) as records:
-            assert partial.doc == "Docstring"
-            assert len(records) == 1
         assert partial.lineno == 3
         assert partial.col_offset == 0
 

tests/test_builder.py

@@ -751,9 +751,6 @@ 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")
-        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)
@@ -797,9 +794,6 @@ def test_function_base_props(self) -> None:
         module = self.module
         function = module["global_access"]
         self.assertEqual(function.name, "global_access")
-        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)
@@ -824,9 +818,6 @@ def test_class_base_props(self) -> None:
         module = self.module
         klass = module["YO"]
         self.assertEqual(klass.name, "YO")
-        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)
@@ -882,9 +873,6 @@ 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"])
-        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)

tests/test_inference.py

@@ -6440,9 +6440,6 @@ def test(self):
     assert isinstance(inferred, objects.Property)
     assert isinstance(inferred.doc_node, nodes.Const)
     assert inferred.doc_node.value == "Docstring"
-    with pytest.warns(DeprecationWarning) as records:
-        assert inferred.doc == "Docstring"
-        assert len(records) == 1
 
 
 def test_recursion_error_inferring_builtin_containers() -> None:

tests/test_nodes.py

@@ -1535,9 +1535,6 @@ def func():
     """
     )
     node: nodes.FunctionDef = astroid.extract_node(code)  # type: ignore[assignment]
-    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
@@ -1553,9 +1550,6 @@ def func():
     """
     )
     node = astroid.extract_node(code)
-    with pytest.warns(DeprecationWarning) as records:
-        assert node.doc is None
-        assert len(records) == 1
     assert node.doc_node is None
 
 

tests/test_raw_building.py

@@ -50,17 +50,11 @@ def test_build_module(self) -> None:
     def test_build_class(self) -> None:
         node = build_class("MyClass")
         self.assertEqual(node.name, "MyClass")
-        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")
-        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:

tests/test_scoped_nodes.py

@@ -13,7 +13,6 @@
 import sys
 import textwrap
 import unittest
-import warnings
 from functools import partial
 from typing import Any
 
@@ -991,9 +990,6 @@ def test_cls_special_attributes_1(self) -> None:
             self.assertEqual(
                 len(cls.getattr("__doc__")), 1, (cls, cls.getattr("__doc__"))
             )
-            with pytest.warns(DeprecationWarning) as records:
-                self.assertEqual(cls.getattr("__doc__")[0].value, cls.doc)
-                assert len(records) == 1
             self.assertEqual(cls.getattr("__doc__")[0].value, cls.doc_node.value)
             self.assertEqual(len(cls.getattr("__module__")), 4)
             self.assertEqual(len(cls.getattr("__dict__")), 1)
@@ -2849,92 +2845,3 @@ def test_non_frame_node():
 
         assert module.body[1].value.locals["x"][0].frame() == module
         assert module.body[1].value.locals["x"][0].frame(future=True) == module
-
-
-def test_deprecation_of_doc_attribute() -> None:
-    code = textwrap.dedent(
-        """\
-    def func():
-        "Docstring"
-        return 1
-    """
-    )
-    node: nodes.FunctionDef = extract_node(code)  # type: ignore[assignment]
-    with pytest.warns(DeprecationWarning) as records:
-        assert node.doc == "Docstring"
-        assert len(records) == 1
-    with pytest.warns(DeprecationWarning) as records:
-        node.doc = None
-        assert len(records) == 1
-
-    code = textwrap.dedent(
-        """\
-    class MyClass():
-        '''Docstring'''
-    """
-    )
-    node: nodes.ClassDef = extract_node(code)  # type: ignore[assignment]
-    with pytest.warns(DeprecationWarning) as records:
-        assert node.doc == "Docstring"
-        assert len(records) == 1
-    with pytest.warns(DeprecationWarning) as records:
-        node.doc = None
-        assert len(records) == 1
-
-    code = textwrap.dedent(
-        """\
-    '''Docstring'''
-    """
-    )
-    node = parse(code)
-    with pytest.warns(DeprecationWarning) as records:
-        assert node.doc == "Docstring"
-        assert len(records) == 1
-    with pytest.warns(DeprecationWarning) as records:
-        node.doc = None
-        assert len(records) == 1
-
-    # If 'doc' isn't passed to Module, ClassDef, FunctionDef,
-    # no DeprecationWarning should be raised
-    doc_node = nodes.Const("Docstring")
-    with warnings.catch_warnings():
-        # Modify warnings filter to raise error for DeprecationWarning
-        warnings.simplefilter("error", DeprecationWarning)
-        node_module = nodes.Module(name="MyModule")
-        node_module.postinit(body=[], doc_node=doc_node)
-        assert node_module.doc_node == doc_node
-        node_class = nodes.ClassDef(
-            name="MyClass",
-            lineno=0,
-            col_offset=0,
-            end_lineno=0,
-            end_col_offset=0,
-            parent=nodes.Unknown(),
-        )
-        node_class.postinit(bases=[], body=[], decorators=[], doc_node=doc_node)
-        assert node_class.doc_node == doc_node
-        node_func = nodes.FunctionDef(
-            name="MyFunction",
-            lineno=0,
-            col_offset=0,
-            parent=node_module,
-            end_lineno=0,
-            end_col_offset=0,
-        )
-        node_func.postinit(
-            args=nodes.Arguments(parent=node_func, vararg=None, kwarg=None),
-            body=[],
-            doc_node=doc_node,
-        )
-        assert node_func.doc_node == doc_node
-
-    # Test 'doc' attribute if only 'doc_node' is passed
-    with pytest.warns(DeprecationWarning) as records:
-        assert node_module.doc == "Docstring"
-        assert len(records) == 1
-    with pytest.warns(DeprecationWarning) as records:
-        assert node_class.doc == "Docstring"
-        assert len(records) == 1
-    with pytest.warns(DeprecationWarning) as records:
-        assert node_func.doc == "Docstring"
-        assert len(records) == 1