Mailman 3 August 2014 - docs

[issue21557] os.popen & os.system lack shell-related security warnings
by Chris Rebert Feb. 13, 2015

Feb. 13, 2015

New submission from Chris Rebert: Since these functions run shell commands, which is a common vector for security-related bugs (see * http://cwe.mitre.org/data/definitions/78.html * http://cwe.mitre.org/data/definitions/88.html ), I suggest that they should have security warning boxes analogous to the one for the `subprocess` module: https://docs.python.org/2/library/subprocess.html#frequently-used-arguments ---------- assignee: docs@python components: Documentation messages: 218921 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: os.popen & os.system lack shell-related security warnings versions: Python 2.7, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21557> _______________________________________

4 8

[issue12954] Multiprocessing logging under Windows
by paul j3 Feb. 10, 2015

Feb. 10, 2015

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

[issue20413] Errors in documentation of standard codec error handlers
by RalfM Feb. 7, 2015

Feb. 7, 2015

New submission from RalfM: The standard library documentation lists the standard codec error handlers in three places: (a) 2. Build-in Functions, section open() (b) 7.2 codecs - Codec registry and base classes (c) 7.2.1 Codec Base Classes As far as I can judge these lists, (c) looks ok, but (a) and (b) contain two errors: 1. 'surrogatepass' is not mentioned. 2. 'surrogateescape' is described as: 'on decoding, replace with code points in the Unicode Private Use Area ranging from U+DC80 to U+DCFF. These private code points will ...' This is incorrect in so far as U+DC80 to U+DCFF are not private code points, but (low-)surrogate code points. This is correctly explained in (c) and in PEP383 (and, of course, in the Unicode standard, chapter 16). I suggest to correct (a) and (b) by * adding 'surrogatepass' with the description given in (c), * changing the description of 'surrogateescape' to something like: 'on decoding, replace with surrogate code points ranging from U+DC80 to U+DCFF. These surrogate code points will ...'. These errors are present in the documentation (more precisely, the .chm files) of at least - Python 3.3.3 - Python 3.3.4rc1 - Python 3.4.0b3. ---------- assignee: docs@python components: Documentation messages: 209477 nosy: RalfM, docs@python priority: normal severity: normal status: open title: Errors in documentation of standard codec error handlers type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20413> _______________________________________

5 5

[issue20702] warning in cmdline.rst
by Antoine Pitrou Jan. 20, 2015

Jan. 20, 2015

New submission from Antoine Pitrou: When building the docs, I get the following message: /home/antoine/cpython/default/Doc/using/cmdline.rst:167: WARNING: Malformed option description u'-?', should look like "-opt args", "--opt args" or "/opt args" ---------- assignee: docs@python components: Documentation messages: 211734 nosy: docs@python, pitrou priority: normal severity: normal status: open title: warning in cmdline.rst versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20702> _______________________________________

3 2

[issue22317] action argument is not documented in argparse add_subparser() docs
by Ubik Jan. 20, 2015

Jan. 20, 2015

New submission from Ubik: See: https://docs.python.org/2/library/argparse.html#argparse.ArgumentParser.add… ---------- assignee: docs@python components: Documentation messages: 226190 nosy: Ubik, docs@python priority: normal severity: normal status: open title: action argument is not documented in argparse add_subparser() docs versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22317> _______________________________________

6 9

[issue20467] Confusing wording about __init__
by Mark Lawrence Jan. 15, 2015

Jan. 15, 2015

New submission from Mark Lawrence: I found the wording here http://docs.python.org/3/reference/datamodel.html#object.__init__ very confusing as it implies that __init__ is the class constructor and not the initialiser. Specifically it says "As a special constraint on constructors, no value may be returned; doing so will cause a TypeError to be raised at runtime". Can we please have the wording changed so that it states exactly what this method does? Possibly changes are also needed in the equivalent section for __new__. ---------- assignee: docs@python components: Documentation messages: 209843 nosy: BreamoreBoy, docs@python priority: normal severity: normal status: open title: Confusing wording about __init__ type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20467> _______________________________________

4 7

[issue21092] json serializer implicitly stringifies non-string keys
by Chris Rebert Jan. 11, 2015

Jan. 11, 2015

New submission from Chris Rebert: Python 3.3.4 (default, Feb 21 2014, 18:00:34) [GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.2.79)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> from json import dumps >>> dumps({True: True, False: False, None: None, 42: 42}) '{"false": false, "true": true, "42": 42, "null": null}' >>> This implicit stringification of non-string dictionary keys does not currently appear to be documented. ---------- assignee: docs@python components: Documentation messages: 215105 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: json serializer implicitly stringifies non-string keys versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21092> _______________________________________

5 4

[issue20487] Odd words in unittest.mock document.
by INADA Naoki Jan. 7, 2015

Jan. 7, 2015

New submission from INADA Naoki: http://docs.python.org/3.3/library/unittest.mock.html#magic-mock > The two equality method, __eq__ and __ne__, are special. They do the default equality comparison on identity, using a side effect, unless you change their return value to return something else: What "using a side effect" means? ---------- assignee: docs@python components: Documentation messages: 209993 nosy: docs@python, michael.foord, naoki priority: normal severity: normal status: open title: Odd words in unittest.mock document. versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20487> _______________________________________

6 8

[issue19548] 'codecs' module docs improvements
by Jan Kaliszewski Jan. 7, 2015

Jan. 7, 2015

New submission from Jan Kaliszewski: When learning about the 'codecs' module I encountered several places in the docs of the module that, I believe, could be improved to be clearer and easier for codecs-begginers: 1. Ad `codecs.encode` and `codecs.decode` descriptions: I believe it would be worth to mention that, unlike str.encode()/bytes.decode(), these functions (and all their counterparts in the classes the module contains) support not only "traditional str/bytes encodings", but also bytes-to-bytes as well as str-to-str encodings. 2. Ad 'codecs.register': in two places there is such a text: `These have to be factory functions providing the following interface: factory([...] errors='strict')` -- `errors='strict'` may be confusing (at the first sight it may suggest that the only valid value is 'strict'; maybe `factory(errors=<error handler label>)` with an appropriate description below would be better?). 3. Ad `codecs.open`: I believe there should be a reference to the built-in open() as an alternative that is better is most cases. 4. Ad `codecs.BOM*`: `These constants define various encodings of the Unicode byte order mark (BOM).` -- the world `encodings` seems to be confusing here; maybe `These constants define various byte sequences being Unicode byte order marks (BOMs) for several encodings. They are used...` would be better? 5. Ad `7.2.1. Codec Base Classes` + `codecs.IncrementalEncoder`/`codecs/IncrementalDecoder`: * `Each codec has to define four interfaces to make it usable as codec in Python: stateless encoder, stateless decoder, stream reader and stream writer` -- only four? Not six? What about incremental encoder/decoder??? * Comparing the fragments (and tables) about error halding methods (Codecs Base Classes, IncrementalEncoder, IncrementalDecoder) with similar fragment in the `codecs.register` description and with the `codecs.register_error` description I was confused: is it the matter of a particular codec implementation or of a registered error handler to implement a particular way of error handling? I believe it would be worth to describe clearly relations between these elements of the API. Also more detailed description of differences beetween error handling for encoding and decoding, and translation would be a good thing. 6. Ad `7.2.1.6. StreamReaderWriter Objects` and `7.2.1.7. StreamRecoder Objects`: It would be worth to say explicitly that, contrary to previously described abstract classes (IncrementalEncoder/Decoder, StreamReader/Writer), these classes are *concrete* ones (if I understand it correctly). 7. Ad `7.2.4. Python Specific Encodings`: * `raw_unicode_encoding` -- see: ticket #19539. * `unicode_encoding` -- `Produce a string that is suitable as Unicode literal in Python source code` but it is *not* a string; it's a *bytes* object (which could be used in source code using an `ascii`-compatibile encoding). * `bytes-to-bytes` and `str-to-str` encodings -- maybe it would be nice to mention that these encodings cannot be used with str.encode()/bytes.decode() methods (and to mention again they *can* be used with the functions/method provided by the `codecs` module). ---------- assignee: docs@python components: Documentation messages: 202593 nosy: docs@python, zuo priority: normal severity: normal status: open title: 'codecs' module docs improvements 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/issue19548> _______________________________________

12 30

[issue20606] Operator Documentation Example doesn't work
by silentbat Jan. 4, 2015

Jan. 4, 2015

New submission from silentbat: In the Docs for Python3.3 http://docs.python.org/3.3/library/operator.html#operator.__setitem__ the following example doesn't work. ---------- assignee: docs@python components: Documentation messages: 211079 nosy: docs@python, silent.bat priority: normal severity: normal status: open title: Operator Documentation Example doesn't work type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20606> _______________________________________

6 7