Title: Missing accepting path-like object in docstrings of os module functions
Type: Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, emilyemorehouse, xiang.zhang
Priority: normal Keywords: easy

Created on 2017-01-22 05:47 by xiang.zhang, last changed 2017-01-24 06:33 by xiang.zhang.

Messages (3)
msg285988 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-01-22 05:47
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 to be examined; can be string, bytes, or open-file-descriptor int.
msg286141 - (view) Author: Emily Morehouse (emilyemorehouse) * Date: 2017-01-24 06:26
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.
msg286143 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-01-24 06:33
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.
Date User Action Args
2017-01-24 06:33:10xiang.zhangsetmessages: + msg286143
2017-01-24 06:26:51emilyemorehousesetnosy: + emilyemorehouse
messages: + msg286141
2017-01-22 06:19:16serhiy.storchakasetkeywords: + easy
assignee: docs@python

components: + Documentation
nosy: + docs@python
2017-01-22 05:48:33xiang.zhangsetstage: needs patch
2017-01-22 05:47:41xiang.zhangcreate