Mailman 3 May 2017 - docs

[issue21649] Mention "Recommendations for Secure Use of TLS and DTLS"
by Antoine Pitrou Sept. 6, 2017

Sept. 6, 2017

New submission from Antoine Pitrou: The IETF has a draft for TLS protocol recommendations, perhaps we can mention it in the ssl module docs: http://tools.ietf.org/html/draft-ietf-uta-tls-bcp ---------- assignee: docs@python components: Documentation messages: 219673 nosy: christian.heimes, docs@python, dstufft, giampaolo.rodola, janssen, pitrou priority: low severity: normal status: open title: Mention "Recommendations for Secure Use of TLS and DTLS" type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21649> _______________________________________

4 9

[issue20762] SSLSocket.read() not documented
by Enrico Bianchi Sept. 5, 2017

Sept. 5, 2017

New submission from Enrico Bianchi: although exists, read() method isn't reported in the SSLSocket documentation. Please, fix it ---------- assignee: docs@python components: Documentation messages: 212115 nosy: docs@python, ebianchi priority: normal severity: normal status: open title: SSLSocket.read() not documented versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20762> _______________________________________

6 8

[issue16988] argparse: PARSER option for nargs not documented
by Robert Leenders Sept. 4, 2017

Sept. 4, 2017

New submission from Robert Leenders: There is a value for nargs: PARSER="A..." which is not documented at http://docs.python.org/3.4/library/argparse.html#nargs. The docstring for the action class in argparse.py also does not list PARSER as a valid value for nargs. In argparse.py on line 2199-2201 it says: # Allow one argument followed by any number of options or arguments elif nargs == PARSER: nargs_pattern = '(-*A[-AO]*)' This is the only hint that I could find on what it is about. ---------- assignee: docs@python components: Documentation messages: 180155 nosy: ReDAeR, bethard, docs@python priority: normal severity: normal status: open title: argparse: PARSER option for nargs not documented type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16988> _______________________________________

5 4

[issue26656] Documentation for re.compile is a bit outdated
by Sworddragon Aug. 28, 2017

Aug. 28, 2017

New submission from Sworddragon: The documentation for re.compile says "Compile a regular expression pattern into a regular expression object, which can be used for matching using its match() and search() methods, described below." which implies that match() and search() are the only methods for it while there are a few more. Maybe this sentence should be worded more generic or at least complete the list. ---------- assignee: docs@python components: Documentation messages: 262571 nosy: Sworddragon, docs@python priority: normal severity: normal status: open title: Documentation for re.compile is a bit outdated type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26656> _______________________________________

12 19

[issue12067] Doc: remove errors about mixed-type comparisons.
by Terry J. Reedy Aug. 24, 2017

Aug. 24, 2017

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Current 3.2 doc, 5.9. Comparisons, has this paragraph about mixed-type comparisons. "The operators <, >, ==, >=, <=, and != compare the values of two objects. The objects need not have the same type. If both are numbers, they are converted to a common type. Otherwise, the == and != operators *always* consider objects of different types to be unequal, while the <, >, >= and <= operators raise a TypeError when comparing objects of different types that do not implement these operators for the given pair of types. You can control comparison behavior of objects of non-built-in types by defining rich comparison methods like __gt__(), described in section Basic customization." Sentence 3: "If both are numbers, they are converted to a common type." I suspect it would be more true to say 'common internal type' as I would not think it a language requirement to produce Python objects. In any case, I think it is only true for built-in number types, and I do not see that qualification anywhere previously. That aside, it does not appear to be true for Decimals and Fractions in 2.7.1. Sentence 4: first clause is only true for built-in types. That qualification is not obvious to everyone, as evidenced by a current python-list sub thread. For 2.7, which has a different continuation, I suggest adding 'built-in' before 'objects of'. For 3.2/3, I suggest deleting '*always*' and adding a comma after 'TypeError' so that the 'when' condition applies to equality comparisons also. After discussion about same-type comparisons, there is another paragraph about mixed-type comparison: "Comparison of objects of the differing types depends on whether either of the types provide explicit support for the comparison. Most numeric types can be compared with one another, but comparisons of float and Decimal are not supported to avoid the inevitable confusion arising from representation issues such as float('1.1') being inexactly represented and therefore not exactly equal to Decimal('1.1') which is. When cross-type comparison is not supported, the comparison method returns NotImplemented. This can create the illusion of non-transitivity between supported cross-type comparisons and unsupported comparisons. For example, Decimal(2) == 2 and 2 == float(2) but Decimal(2) != float(2)." I suggest deleting this entirely. The first sentence and first clause of the second repeat what was said above. The rest is obsolete as float/decimal comparisons *are* implemented in 2.7.1 and 3.2.0. ---------- assignee: docs@python components: Documentation keywords: easy messages: 135873 nosy: docs@python, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Doc: remove errors about mixed-type comparisons. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12067> _______________________________________

15 71

[issue12887] Documenting all SO_* constants in socket module
by Sandro Tosi Aug. 22, 2017

Aug. 22, 2017

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: spinning off msg142613 - it would be interesting to have in the socket module documentation also an explanation of all the several SO_ flags available; even a compact table could be ok; or even a link to a remote reference for them. ---------- assignee: docs@python components: Documentation messages: 143428 nosy: docs@python, eric.araujo, ezio.melotti, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: Documenting all SO_* constants in socket module versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12887> _______________________________________

5 5

[issue14345] Document socket.SOL_SOCKET
by anatoly techtonik Aug. 11, 2017

Aug. 11, 2017

New submission from anatoly techtonik <techtonik(a)gmail.com>: socket.get/setsockopt() docs can be improved by providing description for SOL_SOCKET constant, and link to source code for other level constants and socket level options. ---------- assignee: docs@python components: Documentation messages: 156140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Document socket.SOL_SOCKET _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14345> _______________________________________

3 3

[issue27470] -3 commandline option documented differently via man
by Matthew Gilson Aug. 3, 2017

Aug. 3, 2017

New submission from Matthew Gilson: The man page for python says: > Warn about Python 3.x incompatibilities that 2to3 cannot trivially fix. The official documentation (https://docs.python.org/2/using/cmdline.html#cmdoption-3) does not mention 2to3 at all: > Warn about Python 3.x possible incompatibilities by emitting a DeprecationWarning for features that are removed or significantly changed in Python 3. This seems like a pretty big oversight when the following code issues no warnings (presumably because 2to3 can trivially handle this change): ``` from __future__ import print_function class test(object): def __nonzero__(self): return False t = test() if t: print('Hello') ``` ---------- assignee: docs@python components: Documentation messages: 269994 nosy: docs@python, mgilson priority: normal severity: normal status: open title: -3 commandline option documented differently via man versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27470> _______________________________________

4 5

[issue30304] TestCase.assertMultiLineEqual only registered for Unicode strings in 2.7
by Martin Panter July 25, 2017

July 25, 2017

New submission from Martin Panter: In Mercurial revision 6e5b5d1b6714, the documentation for “assertMultiLineEqual” was changed from This method is used by default when comparing Unicode strings with “assertEqual”. to This method is used by default when comparing strings with “assertEqual”. The new text is misleading because “str” objects are also strings, but the default does not apply to “str” objects. ---------- assignee: docs@python components: Documentation, Tests keywords: easy messages: 293229 nosy: docs@python, ezio.melotti, martin.panter priority: normal severity: normal stage: needs patch status: open title: TestCase.assertMultiLineEqual only registered for Unicode strings in 2.7 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30304> _______________________________________

5 12

[issue26506] hex() documentation: mention "%x" % int
by STINNER Victor July 25, 2017

July 25, 2017

New submission from STINNER Victor: I regulary see Python code using hex(value)[2:], whereas "%x" % value does the same thing. We should mention "%x" % value in the hex() doc. Maybe also mention "%#X" % value to format in upper case? ---------- assignee: docs@python components: Documentation messages: 261308 nosy: docs@python, haypo priority: normal severity: normal status: open title: hex() documentation: mention "%x" % int versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26506> _______________________________________

8 34