[issue12768] docstrings for the threading module
New submission from Eli Bendersky <eliben@gmail.com>: The threading module has very few methods with docstrings. Docstrings should be added to all public methods (contents can be borrowed from the documentation). ---------- assignee: docs@python components: Documentation keywords: easy messages: 142247 nosy: docs@python, eli.bendersky priority: low severity: normal stage: needs patch status: open title: docstrings for the threading module type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Graeme Cross <gjcross@gmail.com> added the comment: Threading module docstrings added for all classes and public methods; mainly used a summarised version of information from the documentation. ---------- keywords: +patch nosy: +gjcross Added file: http://bugs.python.org/file22986/threading_docstrings.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: On Mon, Aug 22, 2011 at 07:39, Graeme Cross <report@bugs.python.org> wrote:
Graeme Cross <gjcross@gmail.com> added the comment:
Threading module docstrings added for all classes and public methods; mainly used a summarised version of information from the documentation.
Thanks for the patch, Graeme. I will try to find time to review and apply it in a few days, if no one else will do it until then. Eli ---------- Added file: http://bugs.python.org/file22987/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: Removed file: http://bugs.python.org/file22987/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Graeme - could you specify which version of Python this patch applies to? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Graeme Cross <gjcross@gmail.com> added the comment: The patch applies to tip. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: The usual procedure for committing to both 3.2 and 3.3 is to apply a patch to 3.2 and then merge it to 3.3 - could you check if the patch also works for 3.2 and if not, generate a patch for 3.2? I will do the merge when committing. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I have made a review on Rietveld. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Éric, yeah I received an email. Hopefully Graeme did too. It's a shame a new review isn't notified in the tracker instead. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Graeme Cross <gjcross@gmail.com> added the comment: I will check that the patch works with 3.2; if not, I'll redo the patch for 3.2. I will also incorporate the review changes from Ezio and Eric. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Graeme, any news on this? If you re-do the patch for current tip and address the review comments, I think we can commit it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
moijes12 added the comment: Hi Is this still open to work on ? If yes, what were the review comments from the previous review? ---------- nosy: +moijes12 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: moijes, Yes, it's open. You can examine the comments for the previous patch by clicking on the "review" link near the patch. You need to be logged in to the issue tracker to see that. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Changes by moijes12 <moijes12@gmail.com>: Added file: http://bugs.python.org/file29268/12768_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
moijes12 added the comment: I've attached a new patch with some changes. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: moijes, did you address the review comments? Does your patch apply to 3.2? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
moijes12 added the comment: Hi I am seen the review comments and made the changes accordingly. I am not sure if my changes apply to 3.2. How do I do that ? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Ezio Melotti added the comment: 3.2$ hg imp --no-c http://bugs.python.org/file29268/12768_2.patch applying http://bugs.python.org/file29268/12768_2.patch patching file Lib/threading.py Hunk #3 FAILED at 58 Hunk #4 FAILED at 79 Hunk #5 FAILED at 92 Hunk #6 FAILED at 125 Hunk #10 FAILED at 252 Hunk #12 succeeded at 386 with fuzz 1 (offset 82 lines). Hunk #13 FAILED at 317 Hunk #17 FAILED at 405 Hunk #22 FAILED at 576 Hunk #23 FAILED at 589 Hunk #30 FAILED at 897 Hunk #33 succeeded at 1124 with fuzz 2 (offset 132 lines). 10 out of 35 hunks FAILED -- saving rejects to file Lib/threading.py.rej abort: patch failed to apply
I am not sure if my changes apply to 3.2. How do I do that ?
You have to switch to the 3.2 branch using "hg up 3.2", and then use "hg import" as showed above to apply the patch. You will also need to run configure/make again to build 3.2, so you can run tests. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Ezio Melotti added the comment: FWIW it applies cleanly on 3.3, but unless we decide to target 3.3+ only, the patch needs to be adapted for 2.7/3.2. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: I wouldn't expend too much effort on older versions though. So unless it's simple to adapt, IMHO 3.3+ is good enough. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
moijes12 added the comment: This patch was built on 3.2(I made the changes on the local repo after running command "hg up 3.2"). I've run the test suite and only test_site failed. This patch has some improvements over 12768_2.patch. ---------- Added file: http://bugs.python.org/file29330/12768_3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Antoine Pitrou added the comment: I haven't read the patch in detail but I think the reference to Java's threading model could probably be discarded. First, I don't know if it's still true, second, I don't think anyone cares :) ---------- nosy: +pitrou stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment:
I haven't read the patch in detail but I think the reference to Java's threading model could probably be discarded. First, I don't know if it's still true, second, I don't think anyone cares :)
I agree. It could be a remnant of a time where the threading library was very new and so it helped "relating" it to something familiar. These days there are (thankfully) many programmers coming to Python without any Java background. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: See also #17375 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
moijes12 added the comment: Hi Since this is a duplicate of #17375, is the patch not going to make to the review stage at all? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: moijes12, since Raymond went ahead and committed a patch to 2.7 in #17375, I think patches to other versions should also be based on his patch. The most constructive thing you can do at this point is review his changes in 2.7 and help porting them to 3.x. Also, you can see if anything is missing/wrong since you've gained some experience about the module while writing the docstrings. I'm sorry it went like that; don't take it personally - open-source development is a bazaar :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Eli Bendersky added the comment: Issue #17375 supersedes this one. Please post updated patches there. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- resolution: -> duplicate status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________
participants (6)
-
Antoine Pitrou -
Eli Bendersky
-
Ezio Melotti
-
Graeme Cross
-
moijes12
-
Éric Araujo