Deprecate passing the doc argument (#1453)

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

Author: DanielNoord

ChangeLog

@@ -13,6 +13,10 @@ Release date: TBA
   ``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``.
 
+* Passing the ``doc`` argument to the ``__init__`` of ``nodes.Module``, ``nodes.ClassDef``,
+  and ``nodes.FunctionDef`` has been deprecated in favour of the ``postinit`` ``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/decorators.py

@@ -224,6 +224,44 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
 
         return deco
 
+    def deprecate_arguments(
+        astroid_version: str = "3.0", **arguments: str
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        """Decorator which emits a DeprecationWarning if any arguments specified
+        are passed.
+
+        Arguments should be a key-value mapping, with the key being the argument to check
+        and the value being a string that explains what to do instead of passing the argument.
+
+        To improve performance, only used when DeprecationWarnings other than
+        the default one are enabled.
+        """
+
+        def deco(func: Callable[P, R]) -> Callable[P, R]:
+            @functools.wraps(func)
+            def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+
+                keys = list(inspect.signature(func).parameters.keys())
+                for arg, note in arguments.items():
+                    try:
+                        index = keys.index(arg)
+                    except ValueError:
+                        raise Exception(
+                            f"Can't find argument '{arg}' for '{args[0].__class__.__qualname__}'"
+                        ) from None
+                    if arg in kwargs or len(args) > index:
+                        warnings.warn(
+                            f"The argument '{arg}' for "
+                            f"'{args[0].__class__.__qualname__}.{func.__name__}' is deprecated "
+                            f"and will be removed in astroid {astroid_version} ({note})",
+                            DeprecationWarning,
+                        )
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return deco
+
 else:
 
     def deprecate_default_argument_values(
@@ -236,3 +274,14 @@ def deco(func: Callable[P, R]) -> Callable[P, R]:
             return func
 
         return deco
+
+    def deprecate_arguments(
+        astroid_version: str = "3.0", **arguments: str
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        """Passthrough decorator to improve performance if DeprecationWarnings are disabled."""
+
+        def deco(func: Callable[P, R]) -> Callable[P, R]:
+            """Decorator function."""
+            return func
+
+        return deco

astroid/nodes/scoped_nodes/scoped_nodes.py

@@ -269,6 +269,7 @@ class Module(LocalsDictNodeNG):
     end_col_offset: None
     parent: None
 
+    @decorators_mod.deprecate_arguments(doc="Use the postinit arg 'doc_node' instead")
     def __init__(
         self,
         name: str,
@@ -1352,6 +1353,7 @@ class FunctionDef(mixins.MultiLineBlockMixin, node_classes.Statement, Lambda):
     )
     _type = None
 
+    @decorators_mod.deprecate_arguments(doc="Use the postinit arg 'doc_node' instead")
     def __init__(
         self,
         name=None,
@@ -2018,6 +2020,7 @@ def my_meth(self, arg):
     _other_other_fields = ("locals", "_newstyle")
     _newstyle = None
 
+    @decorators_mod.deprecate_arguments(doc="Use the postinit arg 'doc_node' instead")
     def __init__(
         self,
         name=None,

tests/unittest_scoped_nodes.py

@@ -2717,6 +2717,15 @@ class MyClass():
         assert node_func.doc == "Docstring"
         assert len(records) == 1
 
+    # If 'doc' is passed to Module, ClassDef, FunctionDef,
+    # a DeprecationWarning should be raised
+    doc_node = nodes.Const("Docstring")
+    with pytest.warns(DeprecationWarning) as records:
+        node_module = nodes.Module(name="MyModule", doc="Docstring")
+        node_class = nodes.ClassDef(name="MyClass", doc="Docstring")
+        node_func = nodes.FunctionDef(name="MyFunction", doc="Docstring")
+        assert len(records) == 3
+
 
 if __name__ == "__main__":
     unittest.main()