From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 2 Aug 2021 18:10:47 +0000 (-0700)
Subject: bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27563)
X-Git-Tag: v3.10.0rc1~3
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=14cb669357bc30bdc235d1c32ee1b99be05ac9d8;p=thirdparty%2FPython%2Fcpython.git

bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27563)

(cherry picked from commit aa0894b3792901adb91e5f6d049154b7bcb980ec)

Co-authored-by: Jake Stockwin <jake.stockwin@optimorlabs.com>
---

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index e2f43424df15..a66b3c5a3a99 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -470,12 +470,16 @@ the :mod:`glob` module.)
    On Windows, splits a pathname into drive/UNC sharepoint and relative path.
 
    If the path contains a drive letter, drive will contain everything
-   up to and including the colon.
-   e.g. ``splitdrive("c:/dir")`` returns ``("c:", "/dir")``
+   up to and including the colon::
+
+      >>> splitdrive("c:/dir")
+      ("c:", "/dir")
 
    If the path contains a UNC path, drive will contain the host name
-   and share, up to but not including the fourth separator.
-   e.g. ``splitdrive("//host/computer/dir")`` returns ``("//host/computer", "/dir")``
+   and share, up to but not including the fourth separator::
+
+      >>> splitdrive("//host/computer/dir")
+      ("//host/computer", "/dir")
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -484,9 +488,24 @@ the :mod:`glob` module.)
 .. function:: splitext(path)
 
    Split the pathname *path* into a pair ``(root, ext)``  such that ``root + ext ==
-   path``, and *ext* is empty or begins with a period and contains at most one
-   period. Leading periods on the basename are  ignored; ``splitext('.cshrc')``
-   returns  ``('.cshrc', '')``.
+   path``, and the extension, *ext*, is empty or begins with a period and contains at
+   most one period.
+
+   If the path contains no extension, *ext* will be ``''``::
+
+      >>> splitext('bar')
+      ('bar', '')
+
+   If the path contains an extension, then *ext* will be set to this extension,
+   including the leading period. Note that previous periods will be ignored::
+
+      >>> splitext('foo.bar.exe')
+      ('foo.bar', '.exe')
+
+   Leading periods on the basename are ignored::
+
+      >>> splitext('.cshrc')
+      ('.cshrc', '')
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
diff --git a/Misc/NEWS.d/next/Documentation/2021-07-22-08-28-03.bpo-35183.p9BWTB.rst b/Misc/NEWS.d/next/Documentation/2021-07-22-08-28-03.bpo-35183.p9BWTB.rst
new file mode 100644
index 000000000000..02c5fe82611f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-07-22-08-28-03.bpo-35183.p9BWTB.rst
@@ -0,0 +1 @@
+Add typical examples to os.path.splitext docs
\ No newline at end of file