Mailman 3 October 2012 - docs

[issue15130] remove redundant paragraph in socket howto
by Tshepang Lekhonkhobe July 25, 2013

July 25, 2013

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: same text used on Abstract is used in the beginning of the main text ---------- assignee: docs@python components: Documentation files: redundancy.diff keywords: patch messages: 163364 nosy: docs@python, tshepang priority: normal severity: normal status: open title: remove redundant paragraph in socket howto versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file26076/redundancy.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15130> _______________________________________

4 4

[issue11908] Weird `slice.stop or sys.maxint`
by Ram Rachum July 11, 2013

July 11, 2013

New submission from Ram Rachum <cool-rr(a)cool-rr.com>: In the documentation for `itertools.islice` I see this line: it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1)) Is it really okay to do `s.stop or sys.maxint`? I'm assuming this was targeting `None`, but what if `s.stop == 0`? And `s.step` could (pathologically) be `0` too, no? ---------- assignee: docs@python components: Documentation messages: 134276 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: Weird `slice.stop or sys.maxint` type: behavior versions: Python 2.5, 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/issue11908> _______________________________________

8 13

[issue14206] multiprocessing.Queue documentation is lacking important details
by Garrett Moore July 2, 2013

July 2, 2013

New submission from Garrett Moore <garrettmoore(a)gmail.com>: 1) If cancel_join_thread() is called, data may be lost. This is not explicitly stated. I had multiple writers put() data in a Queue, and wanted to have the workers finish before I began consuming the data. This caused a deadlock because my Queue was not empty, and it seemed like the a way to force my workers finish was to use cancel_join_thread(). This caused data loss. 2) multiprocessing.Queue states "The Queue class is a near clone of Queue.Queue." Queue.Queue states "If maxsize is less than or equal to zero, the queue size is infinite." mp.Queue provides no information on queue size. It is reasonable to assume then that it inherits the property of Queue.Queue. After discussion on IRC, it seems that mp.Queue maximum size is implementation-dependent and likely relies on how much data Pipes can hold on your platform. If this is the case there should be some mention of the fact that mp.Queue does NOT function like Queue.Queue does for maximum size. ---------- assignee: docs@python components: Documentation messages: 154995 nosy: Garrett.Moore, docs@python priority: normal severity: normal status: open title: multiprocessing.Queue documentation is lacking important details versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14206> _______________________________________

4 4

[issue12716] Reorganize os docs for files/dirs/fds
by Benjamin Peterson June 29, 2013

June 29, 2013

New submission from Benjamin Peterson <benjamin(a)python.org>: Right now many of the os function docs are split up into "Files and directories" and "file descriptor operations". This means, for example, that fchmod() and fchmodat() are in a different section than chmod(). It would make more sense to organize the docs such that functions that do the same thing are right next to each other. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141820 nosy: benjamin.peterson, docs@python priority: low severity: normal status: open title: Reorganize os docs for files/dirs/fds versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12716> _______________________________________

7 9

[issue15818] multiprocessing documentation of Process.exitcode
by Josh Kupershmidt June 24, 2013

June 24, 2013

New submission from Josh Kupershmidt: [I tried to send this as an email to docs(a)python.org yesterday, but it seems to have gotten eaten, as I don't see the message in the archives.] Hi all, The documentation for the multiprocessing module claims: | Note that the start(), join(), is_alive() and exit_code methods | should only be called by the process that created the process object. Two problems with this description: 1. "exit_code" should be spelled "exitcode" 2. exitcode is an attribute of the Process class, not a method as claimed, since the underlying method is decorated with @property Also, aside from the above documentation issues, if it is true that it's not safe to query the exitcode from a separate process, should the exitcode property method include a check like so: assert self._parent_pid == os.getpid(), 'can only test a child process' since start(), join(), and is_alive() all perform this check? ---------- assignee: docs@python components: Documentation messages: 169428 nosy: docs@python, schmiddy priority: normal severity: normal status: open title: multiprocessing documentation of Process.exitcode versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15818> _______________________________________

3 3

[issue14015] surrogateescape largely missing from documentation
by Jim Jewett June 16, 2013

June 16, 2013

New submission from Jim Jewett <jimjjewett(a)gmail.com>: Recent discussion on the mailing lists and in http://bugs.python.org/issue13997 make it clear that the best way to get python2 results for "ASCII-in-the-parts-I-might-process-or-change" is to replace f = open(fname) with f = open(fname, encoding="ascii", errors="surrogateescape") Unfortunately, surrogateescape (let alone this recipe) is not easily discoverable. http://docs.python.org/dev/library/functions.html#open lists 5 error-handlers -- but not this one. It says that other error handlers are possible if they are registered with http://docs.python.org/dev/library/codecs.html#codecs.register_error but I haven't found a way to determine which error handlers are already registered. The codecs.register (as opposed to register_error) documentation does list it as a possible value, but that is the only reference. The other 5 error handlers are also available as module-level functions within the codecs module, and have their own documenation sections within http://docs.python.org/dev/library/codecs.html Neither help(open) nor import codecs; help(codecs) provides any hints of the existence of surrogateescape. Both explicitly suggest that it does not exist, by enumerating other values. ---------- assignee: docs@python components: Documentation, Unicode messages: 153359 nosy: Jim.Jewett, docs@python, ezio.melotti priority: normal severity: normal status: open title: surrogateescape largely missing from documentation versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14015> _______________________________________

5 5

[issue14616] subprocess docs should mention pipes.quote/shlex.quote
by Éric Araujo May 28, 2013

May 28, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: The warning at http://docs.python.org/library/subprocess#frequently-used-arguments should IMO recommend using shlex.quote. Even if it strongly advises against using shell=True, there are people who need or want to use it, so let’s give them a pointer to the quote function. For older versions, I think we should talk about pipes.quote; even if it’s not documented in library/pipes, it is there, it is known and it is used, so I see no harm in mentioning it (with due mention that it’s only semi-official and that it becomes public in 3.3). ---------- assignee: docs@python components: Documentation messages: 158641 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: subprocess docs should mention pipes.quote/shlex.quote versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________

6 19

[issue14009] Clearer documentation for cElementTree
by Éric Araujo May 20, 2013

May 20, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: This patch should clarify how to use cElementTree usage, as well as improving indexing. ---------- assignee: docs@python components: Documentation messages: 153338 nosy: docs@python, eli.bendersky, eric.araujo priority: normal severity: normal stage: commit review status: open title: Clearer documentation for cElementTree versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________

4 13

[issue14878] send statement from PEP342 is poorly documented.
by Stephen Lacy May 10, 2013

May 10, 2013

New submission from Stephen Lacy <slacy(a)slacy.com>: There's reasonable documentation of the yield statement for most python versions under Section 6: Simple Statements, particularly 6.8 "The Yield Statement" (http://docs.python.org/release/2.7/reference/simple_stmts.html#the-yield-st…) But, there's no mention of the return value of the yield statement, or that the send statement even exists. It's mentioned in passing here under "PEP342 New Generator Features" (http://docs.python.org/whatsnew/2.5.html#pep-342-new-generator-features) but should be given fuller explanation and cross-linking from the yield statement documentation. It's also mentioned a bit here: http://docs.python.org/howto/functional.html#passing-values-into-a-generator but again, not under the language documentation itself. ---------- assignee: docs@python components: Documentation messages: 161320 nosy: Stephen.Lacy, docs@python priority: normal severity: normal status: open title: send statement from PEP342 is poorly documented. 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/issue14878> _______________________________________

6 6

[issue14187] add "annotation" entry to Glossary
by Chris Rebert May 6, 2013

May 6, 2013

New submission from Chris Rebert <pybugs(a)rebertia.com>: The Glossary should include an entry for "annotation" and/or "function annotation" regarding the language feature introduced by PEP 3107. ---------- assignee: docs@python components: Documentation messages: 154852 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: add "annotation" entry to Glossary versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________

8 23