Deprecate future argument

ChangeLog

@@ -150,6 +150,8 @@ Release date: TBA
   missing parents regardless of the value of the ``future`` argument (which gave this behavior
   already).
 
+  The ``future`` argument to each method is deprecated and will be removed in astroid 4.0.
+
   Refs #1217
 
 * Remove deprecated ``Ellipsis``, ``ExtSlice``, ``Index`` nodes.

astroid/nodes/node_classes.py

@@ -3814,6 +3814,12 @@ def frame(
 
         :returns: The first parent frame node.
         """
+        if future is not None:
+            warnings.warn(
+                "The future arg will be removed in astroid 4.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if not self.parent:
             raise ParentMissingError(target=self)
 

astroid/nodes/node_ng.py

@@ -293,6 +293,12 @@ def statement(self, *, future: Literal[None, True] = None) -> nodes.Statement:
 
         :raises StatementMissing: If self has no parent attribute.
         """
+        if future is not None:
+            warnings.warn(
+                "The future arg will be removed in astroid 4.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if self.is_statement:
             return cast("nodes.Statement", self)
         if not self.parent:
@@ -310,6 +316,12 @@ def frame(
         :returns: The first parent frame node.
         :raises ParentMissingError: If self has no parent attribute.
         """
+        if future is not None:
+            warnings.warn(
+                "The future arg will be removed in astroid 4.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if self.parent is None:
             raise ParentMissingError(target=self)
         return self.parent.frame(future=future)

astroid/nodes/scoped_nodes/scoped_nodes.py

@@ -382,6 +382,12 @@ def statement(self, *, future: Literal[None, True] = None) -> NoReturn:
 
         When called on a :class:`Module` this raises a StatementMissing.
         """
+        if future is not None:
+            warnings.warn(
+                "The future arg will be removed in astroid 4.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         raise StatementMissing(target=self)
 
     def previous_sibling(self):

tests/test_builder.py

@@ -762,9 +762,10 @@ def test_module_base_props(self) -> None:
         self.assertEqual(module.pure_python, 1)
         self.assertEqual(module.package, 0)
         self.assertFalse(module.is_statement)
-        with pytest.warns(DeprecationWarning) as records:
-            self.assertEqual(module.statement(), module)
-            assert len(records) == 1
+        with self.assertRaises(StatementMissing):
+            with pytest.warns(DeprecationWarning) as records:
+                self.assertEqual(module.statement(future=True), module)
+                assert len(records) == 1
         with self.assertRaises(StatementMissing):
             module.statement()
 

tests/test_nodes.py

@@ -541,16 +541,16 @@ def _test(self, value: Any) -> None:
         self.assertIs(node.value, value)
         self.assertTrue(node._proxied.parent)
         self.assertEqual(node._proxied.root().name, value.__class__.__module__)
-        with self.assertRaises(AttributeError):
+        with self.assertRaises(StatementMissing):
             with pytest.warns(DeprecationWarning) as records:
-                node.statement()
+                node.statement(future=True)
                 assert len(records) == 1
         with self.assertRaises(StatementMissing):
             node.statement()
 
-        with self.assertRaises(AttributeError):
+        with self.assertRaises(ParentMissingError):
             with pytest.warns(DeprecationWarning) as records:
-                node.frame()
+                node.frame(future=True)
                 assert len(records) == 1
         with self.assertRaises(ParentMissingError):
             node.frame()