Mailman 3 October 2012 - docs

[issue14995] PyLong_FromString documentation should state that the string must be null-terminated
by Ryan Kelly March 2, 2014

March 2, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: PyLong_FromString will raise a ValueError if the given string doesn't contain a null byte after the digits. For example, this will result in a ValueError char *pend; PyLong_FromString("1234 extra", &pend, 10) While this will successfully read the number and set the pointer to the extra data: char *pend; PyLong_FromString("1234\0extra", &pend, 10) The requirement for a null-terminated string of digits is not clear from the docs. Suggested re-wording attached. ---------- assignee: docs@python components: Documentation files: PyLong_FromString-doc.patch keywords: patch messages: 162242 nosy: docs@python, rfk priority: normal severity: normal status: open title: PyLong_FromString documentation should state that the string must be null-terminated Added file: http://bugs.python.org/file25812/PyLong_FromString-doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14995> _______________________________________

2 1

[issue13663] pootle.python.org is outdated.
by INADA Naoki Feb. 16, 2014

Feb. 16, 2014

New submission from INADA Naoki <songofacandy(a)gmail.com>: I am one of Japanese translate of Python documents. We have done translating Python 2.7 document and will start translating Python 3.2 or 3.3. I want to use sphinx-i18n and pootle to translate. But http://pootle.python.org/ is very outdated. Anyone can update the site? If nobody maintain the site, could I create Python Document project at http://pootle.locamotion.org/ ? ---------- assignee: docs@python components: Documentation messages: 150261 nosy: docs@python, naoki priority: normal severity: normal status: open title: pootle.python.org is outdated. versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13663> _______________________________________

8 10

[issue14515] tempfile.TemporaryDirectory documented as returning object but returns name
by R. David Murray Feb. 5, 2014

Feb. 5, 2014

New submission from R. David Murray <rdmurray(a)bitdance.com>: The title pretty much says it all. I believe the behavior is correct (more useful than returning an object that is only useful for obtaining the name) even though it is unusual for context managers. In any case there is plenty of code using the existing behavior, so I think this is a doc bug. ---------- assignee: docs@python components: Documentation messages: 157635 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: tempfile.TemporaryDirectory documented as returning object but returns name type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14515> _______________________________________

6 9

[issue12704] Language References does not specify exception raised by final yield()
by Nikolaus Rath Jan. 27, 2014

Jan. 27, 2014

New submission from Nikolaus Rath <Nikolaus(a)rath.org>: >From http://docs.python.org/reference/simple_stmts.html#the-yield-statement: "As of Python version 2.5, the yield statement is now allowed in the try clause of a try ... finally construct. If the generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator’s close() method will be called, allowing any pending finally clauses to execute." This strongly suggests that the last-executed yield statement will raise an exception if the generator is closed. If this is the case, it would be great if the documentation could be extended to say what exception is raised. If this is not the case, it would be great if whatever magic is happening could be documented as well. ---------- assignee: docs@python components: Documentation messages: 141724 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Language References does not specify exception raised by final yield() type: feature request versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________

8 18

[issue11379] Remove "lightweight" from minidom description
by Stefan Behnel Dec. 22, 2013

Dec. 22, 2013

New submission from Stefan Behnel <scoder(a)users.sourceforge.net>: http://docs.python.org/library/xml.dom.minidom.html presents MiniDOM as a "Lightweight DOM implementation". The word "lightweight" is easily misunderstood as meaning "efficient" or "memory friendly". MiniDOM is well known to be neither of the two. The first paragraph then continues: """ xml.dom.minidom is a light-weight implementation of the Document Object Model interface. It is intended to be simpler than the full DOM and also significantly smaller. """ Again, "smaller" can be misread as "low memory footprint", whereas it is actually supposed to refer to an incomplete DOM API implementation. And "simpler" is also clearly exaggerated when compared to the alternative ElementTree package. I would like to see this changed and combined with a clear and visible comment that MiniDOM has very high resource profile, e.g. """ 19.7. xml.dom.minidom — Pure Python DOM implementation xml.dom.minidom is a pure Python implementation of the Document Object Model interface, as known from other programming languages. It is intended to provide a smaller API than the full DOM. Note, however, that MiniDOM has a very large memory footprint compared to other Python XML libraries. If you need a fast and memory friendly XML tree implementation with a vastly simpler API, use the xml.etree package instead. """ ---------- assignee: docs@python components: Documentation messages: 129914 nosy: docs@python, scoder priority: normal severity: normal status: open title: Remove "lightweight" from minidom description versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11379> _______________________________________

12 66

[issue12828] xml.dom.minicompat is not documented
by Sandro Tosi Nov. 12, 2013

Nov. 12, 2013

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: There's no documentation for xml.dom.minicompat - it's a public module and it should have (even a brief) doc. ---------- assignee: docs@python components: Documentation messages: 142845 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: xml.dom.minicompat is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12828> _______________________________________

3 3

[issue13515] Consistent documentation practices for security concerns and considerations
by Nick Coghlan Oct. 21, 2013

Oct. 21, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: This issue proposes that we adopt and apply some standard practices when documenting modules that have potential security implications and other cross-cutting errors that may affect multiple interfaces within the module. Accordingly, the main target is the "Documenting Python" meta-docs, proposing the addition of a new subsection to the Style Guide, with an update to the subprocess module documentation serving as the exemplar of a new recommended style: ====================== 2.6 Security Considerations (and Other Concerns) ------------------------------------------------ Some modules provided with Python are inherently exposed to security issues (e.g. shell injection vulnerabilities) due to the purpose of the module (e.g. subprocess invocation). Littering the documentation of these modules with red warning boxes for problems that are due to the task at hand, rather than specifically to Python's support for that task, doesn't make for a good reading experience. Instead, these security concerns should be gathered into a dedicated "Security Considerations" section within the module's documentation, and cross-referenced from the documentation of affected interfaces with in-line text similar to "Please refer to the :ref:`security-considerations` section for important information on how to avoid common mistakes". Similarly, if there is a common error that affects many interfaces in a module (e.g. OS level pipe buffers filling up and stalling child processes), these can be documented in a "Common Errors" section and cross-referenced rather than repeated for every affected interface. ====================== (based on the thread at http://mail.python.org/pipermail/python-dev/2011-December/114717.html) ---------- assignee: docs@python components: Documentation messages: 148710 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Consistent documentation practices for security concerns and considerations _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________

9 27

[issue16253] Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples
by Roger Upole Oct. 13, 2013

Oct. 13, 2013

New submission from Roger Upole: The docs for this function state "Nested tuples cannot be parsed when using keyword arguments!" but this restriction was removed some time ago. ---------- assignee: docs@python components: Documentation messages: 173081 nosy: docs@python, rupole priority: normal severity: normal status: open title: Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16253> _______________________________________

2 1

[issue14502] Document better what happens on releasing an unacquired lock
by Georg Brandl Oct. 13, 2013

Oct. 13, 2013

New submission from Georg Brandl <georg(a)python.org>: >From docs(a)python.org: """ I recently ran into a situation where I could not be certain that a lock was currently in the acquired state. I checked the documentation to determine what would happen if I attempted to release a lock that was already released, and saw an ominous warning of "Do not call this method when the lock is unlocked." Needing to know what would happen, I cautiously tested it out. I half expected my computer to explode as I released a lock for the second time, but was pleased to see it raise a 'thread.error' exception which could be caught and handled. I generally expect the documentation to tell me what will happen if I do something invalid. In this case the documentation should indicate that a thread.error will be raised if you release an unlocked lock. """ I agree: if we know that a ThreadError will always be raised in this instance, we should document it as such. ---------- assignee: docs@python components: Documentation messages: 157544 nosy: docs@python, georg.brandl, pitrou priority: normal severity: normal status: open title: Document better what happens on releasing an unacquired lock versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14502> _______________________________________

9 23

[issue11120] threading.Thread.daemon Documentation Incomplete
by cardinalbiggles Oct. 13, 2013

Oct. 13, 2013

New submission from cardinalbiggles <jmandersen(a)gmail.com>: In the threading module, the documentation for Thread.isDaemon()/Thread.setDaemon() indicates they are the old API for Thread.daemon, which does not indicate the version in which it was introduced (2.6 I believe). Additionally, the documentation for Thread.setDaemon() should at least include the daemonic parameter, if not the full usage documentation for those targeting older versions. Targeting Python 2.4, and being unable to (as) efficiently navigate the old documentation site, I have come to rely on the various 'Changed/New in version 2.X' messages in the current documentation. This caused some confusion on my part. ---------- assignee: docs@python components: Documentation messages: 127927 nosy: cardinalbiggles, docs@python priority: normal severity: normal status: open title: threading.Thread.daemon Documentation Incomplete type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11120> _______________________________________

2 1