bpo-34329: Doc'd how to remove suffix of pathlib.Path() (GH-8655)
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 3d28a1b..0929ee2 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -559,7 +559,8 @@
.. method:: PurePath.with_suffix(suffix)
Return a new path with the :attr:`suffix` changed. If the original path
- doesn't have a suffix, the new *suffix* is appended instead::
+ doesn't have a suffix, the new *suffix* is appended instead. If the
+ *suffix* is an empty string, the original suffix is removed::
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
@@ -567,6 +568,9 @@
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
+ >>> p = PureWindowsPath('README.txt')
+ >>> p.with_suffix('')
+ PureWindowsPath('README')
.. _concrete-paths:
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 8431c29..4fe9d4a 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -807,8 +807,10 @@
self._parts[:-1] + [name])
def with_suffix(self, suffix):
- """Return a new path with the file suffix changed (or added, if none)."""
- # XXX if suffix is None, should the current suffix be removed?
+ """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
+ string, remove the suffix from the path.
+ """
f = self._flavour
if f.sep in suffix or f.altsep and f.altsep in suffix:
raise ValueError("Invalid suffix %r" % (suffix))