[Python-checkins] bpo-40148: Add PurePath.with_stem() (GH-19295)

[Tim Hoffmann]

https://github.com/python/cpython/commit/8aea4b3605059e243f1827d9328d6fc8d698c0a7
commit: 8aea4b3605059e243f1827d9328d6fc8d698c0a7
branch: master
author: Tim Hoffmann <2836374+timhoffm at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-04-19T17:29:49+02:00
summary:

bpo-40148: Add PurePath.with_stem() (GH-19295)

Add PurePath.with_stem()

files:
A Misc/NEWS.d/next/Library/2020-04-19-14-16-43.bpo-40148.pDZR6V.rst
M Doc/library/pathlib.rst
M Lib/pathlib.py
M Lib/test/test_pathlib.py

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index d4329e7a4c64a..dead49b630dcd 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -571,6 +571,30 @@ Pure paths provide the following methods and properties:
       ValueError: PureWindowsPath('c:/') has an empty name
 
 
+.. method:: PurePath.with_stem(stem)
+
+   Return a new path with the :attr:`stem` changed.  If the original path
+   doesn't have a name, ValueError is raised::
+
+      >>> p = PureWindowsPath('c:/Downloads/draft.txt')
+      >>> p.with_stem('final')
+      PureWindowsPath('c:/Downloads/final.txt')
+      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
+      >>> p.with_stem('lib')
+      PureWindowsPath('c:/Downloads/lib.gz')
+      >>> p = PureWindowsPath('c:/')
+      >>> p.with_stem('')
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in <module>
+        File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
+          return self.with_name(stem + self.suffix)
+        File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
+          raise ValueError("%r has an empty name" % (self,))
+      ValueError: PureWindowsPath('c:/') has an empty name
+
+   .. versionadded:: 3.9
+
+
 .. method:: PurePath.with_suffix(suffix)
 
    Return a new path with the :attr:`suffix` changed.  If the original path
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 88ebe030c7ff7..f98d69eb04ac3 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -870,6 +870,10 @@ def with_name(self, name):
         return self._from_parsed_parts(self._drv, self._root,
                                        self._parts[:-1] + [name])
 
+    def with_stem(self, stem):
+        """Return a new path with the stem changed."""
+        return self.with_name(stem + self.suffix)
+
     def with_suffix(self, suffix):
         """Return a new path with the file suffix changed.  If the path
         has no suffix, add given suffix.  If the given suffix is an empty
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index 8b19cffba37e9..1589282886b6b 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -559,6 +559,23 @@ def test_with_name_common(self):
         self.assertRaises(ValueError, P('a/b').with_name, 'c/')
         self.assertRaises(ValueError, P('a/b').with_name, 'c/d')
 
+    def test_with_stem_common(self):
+        P = self.cls
+        self.assertEqual(P('a/b').with_stem('d'), P('a/d'))
+        self.assertEqual(P('/a/b').with_stem('d'), P('/a/d'))
+        self.assertEqual(P('a/b.py').with_stem('d'), P('a/d.py'))
+        self.assertEqual(P('/a/b.py').with_stem('d'), P('/a/d.py'))
+        self.assertEqual(P('/a/b.tar.gz').with_stem('d'), P('/a/d.gz'))
+        self.assertEqual(P('a/Dot ending.').with_stem('d'), P('a/d'))
+        self.assertEqual(P('/a/Dot ending.').with_stem('d'), P('/a/d'))
+        self.assertRaises(ValueError, P('').with_stem, 'd')
+        self.assertRaises(ValueError, P('.').with_stem, 'd')
+        self.assertRaises(ValueError, P('/').with_stem, 'd')
+        self.assertRaises(ValueError, P('a/b').with_stem, '')
+        self.assertRaises(ValueError, P('a/b').with_stem, '/c')
+        self.assertRaises(ValueError, P('a/b').with_stem, 'c/')
+        self.assertRaises(ValueError, P('a/b').with_stem, 'c/d')
+
     def test_with_suffix_common(self):
         P = self.cls
         self.assertEqual(P('a/b').with_suffix('.gz'), P('a/b.gz'))
@@ -1014,6 +1031,20 @@ def test_with_name(self):
         self.assertRaises(ValueError, P('c:a/b').with_name, 'd:/e')
         self.assertRaises(ValueError, P('c:a/b').with_name, '//My/Share')
 
+    def test_with_stem(self):
+        P = self.cls
+        self.assertEqual(P('c:a/b').with_stem('d'), P('c:a/d'))
+        self.assertEqual(P('c:/a/b').with_stem('d'), P('c:/a/d'))
+        self.assertEqual(P('c:a/Dot ending.').with_stem('d'), P('c:a/d'))
+        self.assertEqual(P('c:/a/Dot ending.').with_stem('d'), P('c:/a/d'))
+        self.assertRaises(ValueError, P('c:').with_stem, 'd')
+        self.assertRaises(ValueError, P('c:/').with_stem, 'd')
+        self.assertRaises(ValueError, P('//My/Share').with_stem, 'd')
+        self.assertRaises(ValueError, P('c:a/b').with_stem, 'd:')
+        self.assertRaises(ValueError, P('c:a/b').with_stem, 'd:e')
+        self.assertRaises(ValueError, P('c:a/b').with_stem, 'd:/e')
+        self.assertRaises(ValueError, P('c:a/b').with_stem, '//My/Share')
+
     def test_with_suffix(self):
         P = self.cls
         self.assertEqual(P('c:a/b').with_suffix('.gz'), P('c:a/b.gz'))
diff --git a/Misc/NEWS.d/next/Library/2020-04-19-14-16-43.bpo-40148.pDZR6V.rst b/Misc/NEWS.d/next/Library/2020-04-19-14-16-43.bpo-40148.pDZR6V.rst
new file mode 100644
index 0000000000000..02a5f9d708410
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-04-19-14-16-43.bpo-40148.pDZR6V.rst
@@ -0,0 +1 @@
+Added :meth:`pathlib.Path.with_stem()` to create a new Path with the stem replaced.
\ No newline at end of file