classification
Title: Missing accepting path-like object in docstrings of os module functions
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BNMetrics, docs@python, emilyemorehouse, fhackdroid, gvanrossum, masthana, pablogsal, vinu2003, xiang.zhang, xtreak
Priority: normal Keywords: easy, patch

Created on 2017-01-22 05:47 by xiang.zhang, last changed 2018-11-02 17:58 by pablogsal. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 10101 merged BNMetrics, 2018-10-25 19:51
PR 10298 merged BNMetrics, 2018-11-02 15:45
PR 10299 merged BNMetrics, 2018-11-02 15:58
Messages (10)
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
        Path to be examined; can be string, bytes, or open-file-descriptor int.
msg286141 - (view) Author: Emily Morehouse (emilyemorehouse) * (Python committer) 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.
msg325263 - (view) Author: Farhaan Bukhsh (fhackdroid) * Date: 2018-09-13 16:59
Hey I would like to make this change which file should I look into?
msg327235 - (view) Author: Vinodhini (vinu2003) * Date: 2018-10-06 07:51
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
msg328337 - (view) Author: Luna Chen (BNMetrics) * Date: 2018-10-23 19:38
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.
msg329134 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2018-11-02 15:20
New changeset b942707fc23454a998323c17e30be78ff1a4f0e7 by Pablo Galindo (BNMetrics) in branch 'master':
bpo-29341: Clarify that path-like objects are accepted in some os methods (GH-10101)
https://github.com/python/cpython/commit/b942707fc23454a998323c17e30be78ff1a4f0e7
msg329147 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2018-11-02 17:55
New changeset 8d2f88fb17468642813108977bb9ec5f7a065b84 by Pablo Galindo (BNMetrics) in branch '3.6':
[3.6]bpo-29341: Backport b942707 3.6 (GH-10299)
https://github.com/python/cpython/commit/8d2f88fb17468642813108977bb9ec5f7a065b84
msg329148 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2018-11-02 17:56
New changeset 08026b103ea8f4c9f2b5045ef7806dd8b760da2b by Pablo Galindo (BNMetrics) in branch '3.7':
[3.7]bpo-29341: Backport b942707 3.7 (#10298)
https://github.com/python/cpython/commit/08026b103ea8f4c9f2b5045ef7806dd8b760da2b
msg329150 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2018-11-02 17:58
The docstrings are fixed and the (manual!) backports to 3.7 and 3.6 are done. Very good job, Luna!
History
Date User Action Args
2018-11-02 17:58:00pablogsalsetmessages: + msg329150
2018-11-02 17:57:52pablogsalsetmessages: - msg329149
2018-11-02 17:57:30pablogsalsetstatus: open -> closed
resolution: fixed
messages: + msg329149

stage: patch review -> resolved
2018-11-02 17:56:29pablogsalsetmessages: + msg329148
2018-11-02 17:55:45pablogsalsetmessages: + msg329147
2018-11-02 15:58:23BNMetricssetpull_requests: + pull_request9608
2018-11-02 15:45:12BNMetricssetpull_requests: + pull_request9607
2018-11-02 15:20:26pablogsalsetnosy: + pablogsal
messages: + msg329134
2018-10-26 21:36:13gvanrossumsetnosy: + gvanrossum
2018-10-25 19:51:19BNMetricssetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request9434
2018-10-23 19:38:53BNMetricssetnosy: + BNMetrics, - thatiparthy
messages: + msg328337
2018-10-23 11:56:11thatiparthysetnosy: + thatiparthy
2018-10-12 15:09:47masthanasetnosy: + masthana
2018-10-06 07:51:27vinu2003setnosy: + vinu2003
messages: + msg327235
2018-09-15 06:46:39xtreaksetnosy: + xtreak
2018-09-13 16:59:34fhackdroidsetnosy: + fhackdroid
messages: + msg325263
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