[Python-checkins] bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27564)

[ambv]

https://github.com/python/cpython/commit/e0d599fa48032eb7b8d837f8412bbca72b6ad820
commit: e0d599fa48032eb7b8d837f8412bbca72b6ad820
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2021-08-02T20:08:10+02:00
summary:

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

(cherry picked from commit aa0894b3792901adb91e5f6d049154b7bcb980ec)

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

files:
A Misc/NEWS.d/next/Documentation/2021-07-22-08-28-03.bpo-35183.p9BWTB.rst
M Doc/library/os.path.rst

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 3be513e9099c78..729649200209b3 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -458,12 +458,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`.
@@ -472,9 +476,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 00000000000000..02c5fe82611fbf
--- /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