classification
Title: Doc cleanup regarding path=fd, dir_fd, follow_symlinks, etc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: larry Nosy List: Arfrever, cheryl.sabella, georg.brandl, kkvr05, larry, vstinner
Priority: normal Keywords: patch

Created on 2012-09-24 15:29 by larry, last changed 2019-05-06 12:40 by larry. This issue is now closed.

Files
File name Uploaded Description Edit
lch.supports_set.doc.cleanup.1.diff larry, 2012-09-24 15:29 First draft at a patch. Doc-only change, docs build clean. review
lch.supports_set.doc.cleanup.1-revised.diff kkvr05, 2013-05-13 22:33 Revised .diff file
Pull Requests
URL Status Linked Edit
PR 5505 merged cheryl.sabella, 2018-02-03 01:20
Messages (9)
msg171155 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2012-09-24 15:29
You know how you start pulling on a thread and before you notice you've unraveled the whole sweater?  I meant to do a simple *one line* fix on the docs and wound up with a nearly-300-line diff.  I claim it's all an improvement, though I'm willing to change it if there's something you don't like.

Definite improvements:
* supports_fd et al are :class:`set` objects, not :class:`~collections.Set`.  Those are different.
* Linked to the "specifying a file descriptor" section in os from the relevant discussion in what's new.
* "Availability: Unix" goes above :versionadded.

Avowed improvements:
* supports_* now explicitly mention what values are permitted for their parameters.
* Lots of rewriting/munging in an effort to improve readability and precision.
* A couple places where "it's" read better than "it is".

LGTU?
msg174705 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2012-11-03 21:50
Patch looks good with two small changes.

* "for consistency's sakes" is used in 2 places; this should be "sake", not the plural "sakes".

* "Normally the *path* argument specified to functions": 'specified to' sounds wrong, and IMHO would be better as 'provided to' or 'passed to'.

The last hunk in the patch to 3.3.rst, but the new text still seems an improvement.
msg189186 - (view) Author: Kaleb Robertson (kkvr05) Date: 2013-05-13 22:33
Adding a revision of the .diff file according to akuchling's comment.
msg189216 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2013-05-14 13:06
Kaleb Robertson's changes look good.  Larry, do you want to go ahead and commit this?
msg189639 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2013-05-20 06:59
I would, but I can't get it to apply cleanly, either to tip or to historical revisions back in Sepember.  Kaleb, what revision is the branch that you generated the diff from?
msg189646 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2013-05-20 09:09
p.s. Thanks for reviving the patch.  I forgot about this one!
msg311530 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-03 01:22
Larry,

I've made a pull request for your patch.  It seemed like most of the original text was still in place, so I thought you might still want these changes.  You had also made changes to the What's New, but I didn't include those changes.
msg341495 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2019-05-06 12:39
New changeset e152169da95b52fa41931572bc90857253c4a5dd by larryhastings (Cheryl Sabella) in branch 'master':
bpo-16024: Doc cleanup regarding path_fd, dir_fd, follow_symlinks (GH-5505)
https://github.com/python/cpython/commit/e152169da95b52fa41931572bc90857253c4a5dd
msg341496 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2019-05-06 12:40
At last!  Thanks for reviving it, Cheryl!
History
Date User Action Args
2019-05-06 12:40:04larrysetstatus: open -> closed
resolution: fixed
messages: + msg341496

stage: patch review -> resolved
2019-05-06 12:39:26larrysetmessages: + msg341495
2018-02-03 01:22:18cheryl.sabellasetnosy: + cheryl.sabella

messages: + msg311530
versions: + Python 3.8, - Python 3.3
2018-02-03 01:20:00cheryl.sabellasetpull_requests: + pull_request5337
2014-12-31 16:31:25akuchlingsetnosy: - akuchling
2013-05-20 09:09:32larrysetmessages: + msg189646
2013-05-20 06:59:19larrysetmessages: + msg189639
2013-05-14 13:06:36akuchlingsetmessages: + msg189216
2013-05-13 22:33:46kkvr05setfiles: + lch.supports_set.doc.cleanup.1-revised.diff
nosy: + kkvr05
messages: + msg189186

2012-11-03 21:50:47akuchlingsetnosy: + akuchling
messages: + msg174705
2012-09-25 00:08:02vstinnersetnosy: + vstinner
2012-09-24 16:32:44Arfreversetnosy: + Arfrever
2012-09-24 15:29:58larrycreate