diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index d4329e7a4c6..dead49b630d 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 "", line 1, in + 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 88ebe030c7f..f98d69eb04a 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 8b19cffba37..1589282886b 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 00000000000..02a5f9d7084 --- /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