bpo-46556: emit `DeprecationWarning` from `pathlib.Path.__enter__()` (GH-30971)

In Python 3.9, Path.__exit__() was made a no-op and has never been documented.

Co-authored-by: Brett Cannon <brett@python.org>

3 files changed, 20 insertions, 12 deletions

diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 7f4210e..4763ab5 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -877,17 +877,20 @@ class Path(PurePath):
         return self._from_parsed_parts(self._drv, self._root, parts)
 
     def __enter__(self):
+        # In previous versions of pathlib, __exit__() marked this path as
+        # closed; subsequent attempts to perform I/O would raise an IOError.
+        # This functionality was never documented, and had the effect of
+        # making Path objects mutable, contrary to PEP 428.
+        # In Python 3.9 __exit__() was made a no-op.
+        # In Python 3.11 __enter__() began emitting DeprecationWarning.
+        # In Python 3.13 __enter__() and __exit__() should be removed.
+        warnings.warn("pathlib.Path.__enter__() is deprecated and scheduled "
+                      "for removal in Python 3.13; Path objects as a context "
+                      "manager is a no-op",
+                      DeprecationWarning, stacklevel=2)
         return self
 
     def __exit__(self, t, v, tb):
-        # https://bugs.python.org/issue39682
-        # In previous versions of pathlib, this method marked this path as
-        # closed; subsequent attempts to perform I/O would raise an IOError.
-        # This functionality was never documented, and had the effect of
-        # making Path objects mutable, contrary to PEP 428. In Python 3.9 the
-        # _closed attribute was removed, and this method made a no-op.
-        # This method and __enter__()/__exit__() should be deprecated and
-        # removed in the future.
         pass
 
     # Public API
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index ec2baca..f03fcbe 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1850,8 +1850,10 @@ class _BasePathTest(object):
         it = p.iterdir()
         it2 = p.iterdir()
         next(it2)
-        with p:
-            pass
+        # bpo-46556: path context managers are deprecated in Python 3.11.
+        with self.assertWarns(DeprecationWarning):
+            with p:
+                pass
         # Using a path as a context manager is a no-op, thus the following
         # operations should still succeed after the context manage exits.
         next(it)
@@ -1859,8 +1861,9 @@ class _BasePathTest(object):
         p.exists()
         p.resolve()
         p.absolute()
-        with p:
-            pass
+        with self.assertWarns(DeprecationWarning):
+            with p:
+                pass
 
     def test_chmod(self):
         p = self.cls(BASE) / 'fileA'
diff --git a/Misc/NEWS.d/next/Library/2022-01-27-23-20-30.bpo-46556.tlpAgS.rst b/Misc/NEWS.d/next/Library/2022-01-27-23-20-30.bpo-46556.tlpAgS.rst
new file mode 100644
index 0000000..1209e0e
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-01-27-23-20-30.bpo-46556.tlpAgS.rst
@@ -0,0 +1,2 @@
+Deprecate undocumented support for using a :class:`pathlib.Path` object as a
+context manager.