Mailman 3 August 2013 - docs

[issue17814] Popen.stdin/stdout/stderr documentation should mention object type
by Nikolaus Rath Jan. 18, 2014

Jan. 18, 2014

New submission from Nikolaus Rath: The subprocess documentation currently just says that Popen.stdin et all are "file objects", which is linked to the glossary entry. This isn't very helpful, as it doesn't tell whether the streams are bytes or text streams. Suggested patch: diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -677,21 +677,29 @@ .. attribute:: Popen.stdin - If the *stdin* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides input to the child process. Otherwise, it is ``None``. + If the *stdin* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedWriter` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides input + to the child process. Otherwise, it is ``None``. .. attribute:: Popen.stdout - If the *stdout* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides output from the child process. Otherwise, it is ``None``. + If the *stdout* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedReader` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides output + from the child process. Otherwise, it is ``None``. .. attribute:: Popen.stderr - If the *stderr* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides error output from the child process. Otherwise, it is - ``None``. + If the *stderr* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedReader` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides output + from the child process. Otherwise, it is ``None``. .. attribute:: Popen.pid ---------- assignee: docs@python components: Documentation messages: 187535 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Popen.stdin/stdout/stderr documentation should mention object type type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17814> _______________________________________

6 10

[issue18011] Inconsistency between b32decode() documentation, docstring and code
by Serhiy Storchaka Jan. 8, 2014

Jan. 8, 2014

New submission from Serhiy Storchaka: b32decode() documentation says: "A TypeError is raised if s were incorrectly padded or if there are non-alphabet characters present in the string." b32decode() docstring says: "binascii.Error is raised if the input is incorrectly padded or if there are non-alphabet characters present in the input." Actually binascii.Error (which is a ValueError subtype) is raised if the input is incorrectly padded and TypeError is raised if there are non-alphabet characters present in the input. At least 2 of 3 (documentation, docstring and implementation) should be corrected. Base32 support was originally added in 3cc0d8fd4e2b (TypeError was used everywhere) and then modified in eb45f85c4c79 (TypeError was partially changed to binascii.Error). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 189571 nosy: barry, docs@python, gvanrossum, serhiy.storchaka priority: normal severity: normal status: open title: Inconsistency between b32decode() documentation, docstring and code type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18011> _______________________________________

4 12

[issue17282] document the defaultTest parameter to unittest.main()
by Chris Jerdonek Jan. 2, 2014

Jan. 2, 2014

New submission from Chris Jerdonek: This issue is to document the defaultTest parameter to unittest.main(): http://docs.python.org/dev/library/unittest.html#unittest.main Note that it is not enough simply to say that *defaultTest* is a "default test name or iterable of test names." The documentation should also say when *defaultTest* is used based on the value of the *module* and *argv* arguments, etc. This issue is an offshoot of issue 15132. ---------- assignee: docs@python components: Documentation keywords: easy messages: 182839 nosy: chris.jerdonek, docs@python, ezio.melotti, michael.foord priority: normal severity: normal stage: needs patch status: open title: document the defaultTest parameter to unittest.main() type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17282> _______________________________________

5 5

[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

[issue18840] Tutorial recommends pickle module without any warning of insecurity
by Donald Stufft Dec. 5, 2013

Dec. 5, 2013

New submission from Donald Stufft: The Python tutorial tells, and even recommends, new users that they can use the pickle module to serialize arbitrary objects. However it does not provide any warning about the insecurity of unpickling arbtirary data. The text even goes so far as to mention sending pickled data over a network connection to other machines. I believe this section should be replaced with using the json module instead of pickle. It is more standard and doesn't present the same security concerns with untrusted data as pickle does. However if it continues to recommend pickle to new users it should at least warn them of the dangers of using pickle. The section in question is located at http://docs.python.org/3/tutorial/inputoutput.html#the-pickle-module ---------- assignee: docs@python components: Documentation messages: 196203 nosy: docs@python, dstufft priority: normal severity: normal status: open title: Tutorial recommends pickle module without any warning of insecurity _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18840> _______________________________________

10 26

[issue18326] Not Clear Docs
by icedream91 Nov. 22, 2013

Nov. 22, 2013

New submission from icedream91: I think the documents talking about list.sort() in page http://docs.python.org/3/library/stdtypes.html#list.sort is not clear enough. What asterisk means in "sort(*, key=None, reverse=None)", may be cmp argument from Python 2, or anything else? Or it is a typo? I think document should explain what this asterisk means. Thanks. ---------- assignee: docs@python components: Documentation messages: 192034 nosy: docs@python, icedream91 priority: normal severity: normal status: open title: Not Clear Docs versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18326> _______________________________________

6 14

[issue18032] set methods should specify whether they consume iterators "lazily"
by Abafei Nov. 19, 2013

Nov. 19, 2013

New submission from Abafei: It says here (http://docs.python.org/2/library/stdtypes.html#set-types-set-frozenset) that some of the set methods take iterables as a parameter. Usually, the expected behavior is for a iterator consumer to consume only as much data as it needs. For example, for the code `any(itertools.repeat(True))`, the code will complete speedily, in contrast to when all() is used instead of any(), in which case the code will go forever. A least some of the set methods have semantics such that they can consume only some of the input; for example, "issubset" only needs to make sure that all of the items in the set are in the iterable, and once this is the case, it can return "True". However in such a case, the methods will *still* go forever. The docs should specify that this is the case, to disambiguate the semantics. (Tested on Python 3.2.3 and 2.7.3). ---------- assignee: docs@python components: Documentation messages: 189806 nosy: Abafei, docs@python priority: normal severity: normal status: open title: set methods should specify whether they consume iterators "lazily" type: behavior versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18032> _______________________________________

5 5

[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

[issue17827] Document codecs.encode and codecs.decode
by Nick Coghlan Nov. 4, 2013

Nov. 4, 2013

New submission from Nick Coghlan: The codecs module has long offered encode() and decode() convenience functions (since 2004: http://hg.python.org/cpython-fullhistory/rev/8ea2cb1ec598), but they're not documented (except through docstrings). We should fix that. >From the docstrings: ========== encode(obj, [encoding[,errors]]) -> object Encodes obj using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is 'strict' meaning that encoding errors raise a ValueError. Other possible values are 'ignore', 'replace' and 'xmlcharrefreplace' as well as any other name registered with codecs.register_error that can handle ValueErrors. ========== decode(obj, [encoding[,errors]]) -> object Decodes obj using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is 'strict' meaning that encoding errors raise a ValueError. Other possible values are 'ignore' and 'replace' as well as any other name registered with codecs.register_error that is able to handle ValueErrors. ========== Note that the difference between the convenience functions in the codecs module and the methods on str, bytes and bytearray is that the latter have additional type checks to limit their usage to text encodings. str.encode expects a str->bytes conversion, while bytes.decode and bytearray.decode both expect the codec to produce a str object. codecs.encode and codecs.decode are both arbitrary object->object conversions, limited only by whatever the chosen codec supports. ---------- assignee: docs@python components: Documentation messages: 187700 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Document codecs.encode and codecs.decode versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17827> _______________________________________

7 16

[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