[Python-checkins] bpo-34329: Doc'd how to remove suffix of pathlib.Path() (GH-8655)

[Berker Peksag]

https://github.com/python/cpython/commit/39fcd9949832323b672f7ff05fd1498b8844a329
commit: 39fcd9949832323b672f7ff05fd1498b8844a329
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Berker Peksag <berker.peksag at gmail.com>
date: 2018-08-04T00:45:46+03:00
summary:

bpo-34329: Doc'd how to remove suffix of pathlib.Path() (GH-8655)

(cherry picked from commit 46dc4e34ed8005a688d7f3512844ef227a3465f4)

Co-authored-by: Stefan Otte <stefan.otte at gmail.com>

files:
M Doc/library/pathlib.rst
M Lib/pathlib.py

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 3d28a1bea303..0929ee27c19e 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -559,7 +559,8 @@ Pure paths provide the following methods and properties:
 .. 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 @@ Pure paths provide the following methods and properties:
       >>> 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 8431c29c1d65..4fe9d4aefc3b 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -807,8 +807,10 @@ def with_name(self, name):
                                        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))