Mailman 3 October 2012 - docs

[issue13386] Document documentation conventions for optional args
by Ezio Melotti 20 Apr '15

20 Apr '15

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: AFAIU the conventions for optional argument in the doc are as follow: If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example: str.splitlines(keepends=False) If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. This should apply only to some C functions, for example: str.strip([chars]) The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted. These rules apply to both Python 2 and Python 3. A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function. ---------- assignee: docs@python components: Documentation messages: 147469 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: needs patch status: open title: Document documentation conventions for optional args versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13386> _______________________________________

10 29

[issue15566] tarfile.TarInfo.frombuf documentation is out of date
by Sebastian Ramacher 19 Apr '15

19 Apr '15

New submission from Sebastian Ramacher: tarfile.TarInfo.frombuf has gained two more parameters: encoding and errors. The documentation of frombuf claims that the only parameter is buf, which is not true anymore. ---------- assignee: docs@python components: Documentation messages: 167553 nosy: docs@python, sebastinas priority: normal severity: normal status: open title: tarfile.TarInfo.frombuf documentation is out of date versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15566> _______________________________________

6 5

[issue12652] Move documentation of test.support into the devguide
by Eli Bendersky 14 Apr '15

14 Apr '15

New submission from Eli Bendersky <eliben(a)gmail.com>: First step in transition: Attaching a patch to devguide's runtests.rst to incorporate existing test.support documentation from 3.3 head, with some small markup changes suitable for the devguide. ---------- components: Devguide files: devguide_test_support.1.patch keywords: patch messages: 141337 nosy: brett.cannon, docs@python, eli.bendersky, ncoghlan priority: low severity: normal stage: patch review status: open title: Move documentation of test.support into the devguide type: behavior Added file: http://bugs.python.org/file22790/devguide_test_support.1.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12652> _______________________________________

10 12

[issue12955] urllib2.build_opener().open() is not friendly to "with ... as:"
by Valery Khamenya 12 Apr '15

12 Apr '15

New submission from Valery Khamenya <khamenya(a)gmail.com>: The following intuitive construction with urllib2.build_opener().open() as: ... leads to AttributeError: addinfourl instance has no attribute '__exit__' http://docs.python.org/library/urllib2.html says almost nothing about concept of closing. Could it be possible to add a canonical "with ... as:" example for urllib2.build_opener() ? Thanks, Valery ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 143836 nosy: Valery.Khamenya, docs@python priority: normal severity: normal status: open title: urllib2.build_opener().open() is not friendly to "with ... as:" type: resource usage versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12955> _______________________________________

9 17

[issue11468] Improve unittest basic example in the doc
by Ezio Melotti 24 Mar '15

24 Mar '15

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: The current example[0] uses assertTrue(element in self.seq) but it would be better to use assertIn instead. The whole example could be changed to something simpler that uses only the assertTrue/assertEqual/assertRaises methods correctly, e.g.: import unittest class TestStringMethods(unittest.TestCase): def test_upper(self): self.assertEqual('foo'.upper(), 'FOO') def test_isupper(self): self.assertTrue('FOO'.isupper()) self.assertFalse('Foo'.isupper()) def test_split(self): s = 'hello world' self.assertEqual(s.split(), ['hello', 'world']) # check that s.split fails when the separator is not a string with self.assertRaises(TypeError): s.split(2) if __name__ == '__main__': unittest.main() [0]: http://docs.python.org/py3k/library/unittest.html#basic-example ---------- assignee: docs@python components: Documentation keywords: easy messages: 130598 nosy: docs@python, eric.araujo, ezio.melotti, michael.foord, ncoghlan, rhettinger priority: low severity: normal stage: needs patch status: open title: Improve unittest basic example in the doc type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________

9 19

[issue12155] queue example doesn't stop worker threads
by STINNER Victor 18 Mar '15

18 Mar '15

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The queue doc contains the following example: ------------------ def worker(): while True: item = q.get() do_work(item) q.task_done() q = Queue() for i in range(num_worker_threads): t = Thread(target=worker) t.daemon = True t.start() for item in source(): q.put(item) q.join() # block until all tasks are done ------------------ http://docs.python.org/library/queue.html It doesn't define do_work(), num_worker_threads or do_work(), but my concern is that it doesn't stop worker threads. I consider "t.daemon = True" as an hack to not care about stopping threads. The example should pass a special value to each worker to stop it. For example: <worker> while True: job = queue.get() if job is None: break audio.play(*job) queue.task_done() Main thread: ... threads = [] for i in range(num_worker_threads): t = Thread(target=worker) threads.append(t) t.start() ... for i in range(num_worker_threads): queue.put(None) queue.join() for thread in threads: thread.join() ---------- assignee: docs@python components: Documentation messages: 136601 nosy: docs@python, haypo, pitrou priority: normal severity: normal status: open title: queue example doesn't stop worker threads versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12155> _______________________________________

5 7

[issue9119] Python download page needs to mention crypto code in Windows installer
by Marc-Andre Lemburg 20 Feb '15

20 Feb '15

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: This needs to be done to protect our users (importing crypto code or using it may be illegal in their home country, see http://rechten.uvt.nl/koops/cryptolaw/ for a survey) and to satisfy an attribution requirement in the OpenSSL license and code base: """ This product includes cryptographic software written by Eric Young (eay(a)cryptsoft.com). This product includes software written by Tim Hudson (tjh(a)cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) """ ---------- assignee: docs@python components: Build, Documentation messages: 108929 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Python download page needs to mention crypto code in Windows installer versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9119> _______________________________________

10 23

[issue9913] Misc/SpecialBuilds.txt is out of date
by Alexander Belopolsky 18 Feb '15

18 Feb '15

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: It looks like Misc/SpecialBuilds.txt has not been updated since 2.4. This file is referenced from C-API documentation [1], but is not accessible as a hyperlink. Some of the recommendations in this file are out of date, in particular those that recommend setting make variables where a configure switch is available. I believe it would be best to retire Misc/SpecialBuilds.txt and move still relevant sections to proper .rst files. [1] http://docs.python.org/dev/py3k/c-api/intro.html#debugging-builds ---------- assignee: docs@python components: Documentation messages: 117076 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Misc/SpecialBuilds.txt is out of date versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9913> _______________________________________

3 3

[issue14512] Pydocs module docs server not working on Windows.
by Terry J. Reedy 16 Feb '15

16 Feb '15

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: 3.2.3rc2 and 3.3.0a2, freshly downloaded and installed, Win7, 64 bit Start Menue/Pythonxx/Module Docs Brings up tkinter pydoc box. [open browser] brings up *empty* localhost:7464 window. Search 'tkinter' and double-click tkinter entry or select and [go to selected] opens empty localhost:7464/tkinter.html window. This worked sometime last year on earlier 3.2, maybe on xp box. I thought there might be an issue already, but I searched for 'pydoc' and 'modole docs' and found nothing. ---------- assignee: docs@python components: Documentation, Installation, Library (Lib) messages: 157606 nosy: docs@python, georg.brandl, loewis, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Pydocs module docs server not working on Windows. type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14512> _______________________________________

6 10

[issue12954] Multiprocessing logging under Windows
by paul j3 10 Feb '15

10 Feb '15

New submission from paul j3 <ajipanca(a)gmail.com>: The Windows programming guidelines for the multiprocessing module documentation should include a warning that any logging initialization should be protected by the 'if __name__' block. Otherwise you will get duplicate logging entries for the child processes. This is because the multiprocessing.forking.prepare() function explicitly calls log_to_stderr(), and may implicitly do so again when it imports the parent module, resulting in duplicate logging handlers. ---------- assignee: docs@python components: Documentation messages: 143815 nosy: docs@python, paul.j3 priority: normal severity: normal status: open title: Multiprocessing logging under Windows _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12954> _______________________________________

4 9