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

Missing accepting path-like object in docstrings of os module functions #73527

Closed
zhangyangyu opened this issue Jan 22, 2017 · 10 comments
Closed

Missing accepting path-like object in docstrings of os module functions #73527

zhangyangyu opened this issue Jan 22, 2017 · 10 comments
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir easy

Comments

@zhangyangyu
Copy link
Member

BPO 29341
Nosy @gvanrossum, @zhangyangyu, @emilyemorehouse, @pablogsal, @vinu2003, @farhaanbukhsh, @tirkarthi, @BNMetrics, @mayankasthana
PRs
  • bpo-29341: Added path.like object to docstring in posixmodule.c and posixmodule.c.h #10101
  • [3.7]bpo-29341: Backport b942707 3.7 #10298
  • [3.6]bpo-29341: Backport b942707 3.6 #10299
    		•

    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 2018-11-02.17:57:30.626>
created_at = <Date 2017-01-22.05:47:41.547>
labels = ['easy', '3.7', 'docs']
title = 'Missing accepting path-like object in docstrings of os module functions'
updated_at = <Date 2018-11-02.17:58:00.885>
user = 'https://github.com/zhangyangyu'

    bugs.python.org fields:

    activity = <Date 2018-11-02.17:58:00.885>
actor = 'pablogsal'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-11-02.17:57:30.626>
closer = 'pablogsal'
components = ['Documentation']
creation = <Date 2017-01-22.05:47:41.547>
creator = 'xiang.zhang'
dependencies = []
files = []
hgrepos = []
issue_num = 29341
keywords = ['patch', 'easy']
message_count = 10.0
messages = ['285988', '286141', '286143', '325263', '327235', '328337', '329134', '329147', '329148', '329150']
nosy_count = 10.0
nosy_names = ['gvanrossum', 'docs@python', 'xiang.zhang', 'emilyemorehouse', 'pablogsal', 'vinu2003', 'fhackdroid', 'xtreak', 'BNMetrics', 'masthana']
pr_nums = ['10101', '10298', '10299']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29341'
versions = ['Python 3.6', 'Python 3.7']
    @zhangyangyu
    Copy link
    Member Author

    PathLike objects are added in 3.6 and they are mentioned in the documentation. But in some os module functions' docstrings, acceptable types of path parameter are mentioned and they are not altered to mention path-like object. For example:

    chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
    Change the owner and group id of path to the numeric uid and gid.\
    
      path
        Path to be examined; can be string, bytes, or open-file-descriptor int.

    @zhangyangyu zhangyangyu added the 3.7 (EOL) end of life label Jan 22, 2017
    @serhiy-storchaka serhiy-storchaka added easy docs Documentation in the Doc dir labels Jan 22, 2017
    @emilyemorehouse
    Copy link
    Member

    I see that path-like objects are indeed mentioned in the documentation (Doc/library/os.rst), simply stating "Changed in version 3.6: Supports a path-like object." Other methods, such as os.chroot, also mention such a change.

    Comparing the docs mentioned above to the docstrings in Modules/clinic/posixmodule.c.h (and Modules/clinic/posixmodule.c for that matter), there's a clear disparity between the detail in the docs vs brevity in the docstrings (specifically in reference to os.chroot).

    Therefore, my question is: how detailed should the docstrings be and how closely should they match Doc/library/os.rst? I can certainly update the docstrings accordingly.

    @zhangyangyu
    Copy link
    Member Author

    I don't mean to sync the docstring and the documentation totally. But just like os.chown, there are some functions explicitly mention the acceptable types of path parameter in their docstrings. I think since they already mention the types, then make the list complete. For example, I think for os.chown make the list "can be string, bytes, path-like object or open-file-descriptor int" is enough.

    @farhaanbukhsh
    Copy link
    Mannequin

    farhaanbukhsh mannequin commented Sep 13, 2018

    Hey I would like to make this change which file should I look into?

    @vinu2003
    Copy link
    Mannequin

    vinu2003 mannequin commented Oct 6, 2018

    This is now carried forward in 3.8 also. Is anyone working on this issue ?
    It needs to be corrected in doc-string for all method where its applicable

    @BNMetrics
    Copy link
    Mannequin

    BNMetrics mannequin commented Oct 23, 2018

    Farhaan Bukhsh: you said you wanted to work on this but that was over a month ago, so I presume you've directed your attention elsewhere, and I'd like to give this a try.

    @pablogsal
    Copy link
    Member

    New changeset b942707 by Pablo Galindo (BNMetrics) in branch 'master':
    bpo-29341: Clarify that path-like objects are accepted in some os methods (GH-10101)
    b942707

    @pablogsal
    Copy link
    Member

    New changeset 8d2f88f by Pablo Galindo (BNMetrics) in branch '3.6':
    [3.6]bpo-29341: Backport b942707 3.6 (GH-10299)
    8d2f88f

    @pablogsal
    Copy link
    Member

    New changeset 08026b1 by Pablo Galindo (BNMetrics) in branch '3.7':
    [3.7]bpo-29341: Backport b942707 3.7 (bpo-10298)
    08026b1

    @pablogsal
    Copy link
    Member

    The docstrings are fixed and the (manual!) backports to 3.7 and 3.6 are done. Very good job, Luna!

    @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.7 (EOL) end of life docs Documentation in the Doc dir easy
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    4 participants
    @serhiy-storchaka @zhangyangyu @emilyemorehouse @pablogsal