Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

os.path.splitext documentation needs typical example #79364

Closed
shaungriffith mannequin opened this issue Nov 7, 2018 · 8 comments
Closed

os.path.splitext documentation needs typical example #79364

shaungriffith mannequin opened this issue Nov 7, 2018 · 8 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@shaungriffith
Copy link
Mannequin

shaungriffith mannequin commented Nov 7, 2018

BPO 35183
Nosy @ambv, @miss-islington, @jdevries3133, @jstockwin
PRs
  • bpo-35183: Add typical examples to os.path.splitext docs #27286
  • [3.10] bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) #27563
  • [3.9] bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) #27564
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2021-08-02.18:12:04.752>
created_at = <Date 2018-11-07.11:49:12.969>
labels = ['easy', '3.9', '3.10', '3.11', 'type-feature', 'library', 'docs']
title = 'os.path.splitext documentation needs typical example'
updated_at = <Date 2021-08-02.18:12:04.752>
user = 'https://bugs.python.org/shaungriffith'

    bugs.python.org fields:

    activity = <Date 2021-08-02.18:12:04.752>
actor = 'lukasz.langa'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-08-02.18:12:04.752>
closer = 'lukasz.langa'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2018-11-07.11:49:12.969>
creator = 'shaungriffith'
dependencies = []
files = []
hgrepos = []
issue_num = 35183
keywords = ['patch', 'easy']
message_count = 8.0
messages = ['329414', '397946', '397967', '397981', '398784', '398789', '398790', '398791']
nosy_count = 6.0
nosy_names = ['docs@python', 'lukasz.langa', 'miss-islington', 'shaungriffith', 'jack__d', 'jstockwin']
pr_nums = ['27286', '27563', '27564']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35183'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
    @shaungriffith
    Copy link
    Mannequin Author

    shaungriffith mannequin commented Nov 7, 2018

    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')

    @shaungriffith shaungriffith mannequin assigned docspython Nov 7, 2018
    @shaungriffith shaungriffith mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Nov 7, 2018
    @iritkatriel iritkatriel added easy stdlib Python modules in the Lib dir 3.9 only security fixes 3.10 only security fixes 3.11 only security fixes labels Jun 22, 2021
    @jstockwin
    Copy link
    Mannequin

    jstockwin mannequin commented Jul 21, 2021

    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).

    @jdevries3133
    Copy link
    Mannequin

    jdevries3133 mannequin commented Jul 21, 2021

    @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.
    2. 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!

    @jstockwin
    Copy link
    Mannequin

    jstockwin mannequin commented Jul 22, 2021

    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.

    @ambv
    Copy link
    Contributor

    ambv commented Aug 2, 2021

    New changeset aa0894b by Jake Stockwin in branch 'main':
    bpo-35183: Add typical examples to os.path.splitext docs (GH-27286)
    aa0894b

    @ambv
    Copy link
    Contributor

    ambv commented Aug 2, 2021

    New changeset e0d599f by Miss Islington (bot) in branch '3.9':
    bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27564)
    e0d599f

    @ambv
    Copy link
    Contributor

    ambv commented Aug 2, 2021

    New changeset 14cb669 by Miss Islington (bot) in branch '3.10':
    bpo-35183: Add typical examples to os.path.splitext docs (GH-27286) (GH-27563)
    14cb669

    @ambv
    Copy link
    Contributor

    ambv commented Aug 2, 2021

    Thanks, Jake! ✨ 🍰 ✨

    @ambv ambv closed this as completed Aug 2, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    2 participants
    @ambv @iritkatriel