classification
Title: os.path.splitext documentation needs typical example
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, jack__d, jstockwin, lukasz.langa, miss-islington, shaungriffith
Priority: normal Keywords: easy, patch

Created on 2018-11-07 11:49 by shaungriffith, last changed 2021-08-02 18:12 by lukasz.langa. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 27286 merged jstockwin, 2021-07-22 08:27
PR 27563 merged miss-islington, 2021-08-02 17:02
PR 27564 merged miss-islington, 2021-08-02 17:02
Messages (8)
msg329414 - (view) Author: Shaun Griffith (shaungriffith) Date: 2018-11-07 11:49
As with many entries on the os.path doc page, splitext needs a typical example. Not grokking the bare minimum text, I had to actually try it in the interpreter to see what it did.

The one example that *is* there is an edge case, and does nothing to explain the normal behavior, or why this is the correct behavior for the edge case.

Here is where I tripped up:

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.

One interpretation of this is that ext is either empty, or has a period, _and nothing else_. 

Here are 2 examples for typical use:

>>> splitext('readme.txt')
('readme', '.txt')
>>> splitext('/some/long/pathname/warble.csv')
('/some/long/pathname/warble', '.csv')
msg397946 - (view) Author: Jake Stockwin (jstockwin) * Date: 2021-07-21 14:09
Hello, I would like to submit a PR for this.

It'll be my first contribution to cPython and I am slightly unclear if this suggestion has been "accepted" in some sense (i.e. do the Devs agree it should be fixed as suggested)?

If so, I will go ahead and create PR (and credit shaungriffith for his provided examples).
msg397967 - (view) Author: Jack DeVries (jack__d) * Date: 2021-07-21 23:21
@jstockwin, the process usually goes like this:

1. You open a PR
2. The discussion continues over there. non-core-dev volunteers review your PR and get it into a polished state.
3. A core dev will quickly take a look, provide feedback if necessary, or just merge if not.

There's no need to credit anyone – if Shaun wanted credit, he could have included a PR with his bug report! Plus, the commit will include this bpo#, so future onlookers can always trace the commit back to this thread.

Follow the dev guide as you go and don't hesitate to post any questions you have right here!
msg397981 - (view) Author: Jake Stockwin (jstockwin) * Date: 2021-07-22 09:15
Thanks for the info, @jack__d - very helpful.
I have now submitted a PR for this and will await a review. Let me know if anything else is needed.
msg398784 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-02 17:02
New changeset aa0894b3792901adb91e5f6d049154b7bcb980ec by Jake Stockwin in branch 'main':
bpo-35183: Add typical examples to os.path.splitext docs (GH-27286)
https://github.com/python/cpython/commit/aa0894b3792901adb91e5f6d049154b7bcb980ec
msg398789 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-02 18:08
New changeset e0d599fa48032eb7b8d837f8412bbca72b6ad820 by Miss Islington (bot) in branch '3.9':
bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27564)
https://github.com/python/cpython/commit/e0d599fa48032eb7b8d837f8412bbca72b6ad820
msg398790 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-02 18:10
New changeset 14cb669357bc30bdc235d1c32ee1b99be05ac9d8 by Miss Islington (bot) in branch '3.10':
bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27563)
https://github.com/python/cpython/commit/14cb669357bc30bdc235d1c32ee1b99be05ac9d8
msg398791 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-02 18:12
Thanks, Jake! ✨ 🍰 ✨
History
Date User Action Args
2021-08-02 18:12:04lukasz.langasetstatus: open -> closed
resolution: fixed
messages: + msg398791

stage: patch review -> resolved
2021-08-02 18:10:54lukasz.langasetmessages: + msg398790
2021-08-02 18:08:35lukasz.langasetmessages: + msg398789
2021-08-02 17:02:09miss-islingtonsetpull_requests: + pull_request26071
2021-08-02 17:02:02miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request26070
2021-08-02 17:02:02lukasz.langasetnosy: + lukasz.langa
messages: + msg398784
2021-07-22 09:15:13jstockwinsetmessages: + msg397981
2021-07-22 08:27:24jstockwinsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25828
2021-07-21 23:21:07jack__dsetnosy: + jack__d
messages: + msg397967
2021-07-21 14:09:15jstockwinsetnosy: + jstockwin
messages: + msg397946
2021-06-22 22:50:24iritkatrielsetkeywords: + easy
components: + Library (Lib)
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.6
2018-12-24 06:02:32serhiy.storchakalinkissue35576 superseder
2018-11-07 11:49:12shaungriffithcreate