Mailman 3 November 2015 - docs

some RFC references could be updated
by Sean Turner 10 Jun '17

10 Jun '17

Hi, Just starting to learn python and have noted that at the bottom of this page: http://docs.python.org/3/library/ssl.html There's a couple of out of date references: 0) RFC 1750 has been been obsoleted by RFC 4086 so maybe this is a better reference (and I prefer the datatracker view as opposed to the tools view): http://datatracker.ietf.org/doc/rfc4086/ Same could be done on this link: http://docs.python.org/3.4/library/ssl.html 1) RFC 3280 has been obsoleted by RFC 5280 so maybe: http://datatracker.ietf.org/doc/rfc5280/ Same could be done on this link: http://docs.python.org/3.4/library/ssl.html 2) RFC 4366 has been obsoleted by RFC 6066 so maybe: http://datatracker.ietf.org/doc/rfc6066/ On http://docs.python.org/3.4/library/ssl.html you could probably just drop the reference and change in the ssl.HAS_SNI section. 3) The link to TLS seems broken maybe just point to: TLS 1.0 http://datatracker.ietf.org/doc/rfc2246/ TLS 1.1 http://datatracker.ietf.org/doc/rfc4346/ TLS 1.2 http://datatracker.ietf.org/doc/rfc5246/ SSL 3.0 http://datatracker.ietf.org/doc/rfc6101/ Actually the same link is broken on: http://docs.python.org/3.4/library/ssl.html 4) (this is a shameless plug) Might be worth adding a reference in the ssl.PROTOCOL_SSLv2 section that points to: http://datatracker.ietf.org/doc/rfc6146/ Cheers, spt

10 20

[issue24755] asyncio.wrap_future undocumented
by Marcin Szewczyk 09 Jun '17

09 Jun '17

New submission from Marcin Szewczyk: While asyncio.wrap_future is mentioned in PEP 3156 and has its docstring it is undocumented in the reference. run_in_executor is documented but doesn't mention wrap_future either. $ grep -r wrap_future Doc; echo $? 1 ---------- assignee: docs@python components: Documentation messages: 247659 nosy: docs@python, wodny priority: normal severity: normal status: open title: asyncio.wrap_future undocumented type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24755> _______________________________________

7 12

[issue23787] sum() function docstring lists arguments incorrectly
by Valentine Sinitsyn 06 Jun '17

06 Jun '17

New submission from Valentine Sinitsyn: sum() function doctstring describes expected arguments as follows (Python 2.7.6): sum(...) sum(sequence[, start]) -> value ... This implies sum() should accept str, unicode, list, tuple, bytearray, buffer, and xrange. However, you clearly can't use this function to sum strings (which is also mentioned in the docstring): >>> sum('abc') Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: unsupported operand type(s) for +: 'int' and 'str' I'd suggest to describe first argument as iterable, which is actually what sum() expects there. ---------- assignee: docs@python components: Documentation messages: 239388 nosy: docs@python, vsinitsyn priority: normal severity: normal status: open title: sum() function docstring lists arguments incorrectly type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23787> _______________________________________

6 13

[issue24899] Add an os.path <=> pathlib equivalence table in pathlib docs
by Ezio Melotti 02 Jun '17

02 Jun '17

New submission from Ezio Melotti: I think it would be useful to add to the pathlib documentation a table listing os/os.path operations and their pathlib equivalent. This will be useful both for people porting their code to pathlib and for people that already know os/os.path and want to get familiar with pathlib. ---------- assignee: docs@python components: Documentation keywords: easy messages: 248877 nosy: docs@python, ezio.melotti, pitrou priority: normal severity: normal stage: needs patch status: open title: Add an os.path <=> pathlib equivalence table in pathlib docs type: enhancement versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24899> _______________________________________

7 10

[issue24692] types.coroutines() idempotence documentation
by Antoine Pietri 01 Jun '17

01 Jun '17

New submission from Antoine Pietri: In the new types.coroutines() documentation, it is not clearly stated whether this function is idempotent or not: what happens when it is called on a function that is already a native coroutine? ---------- assignee: docs@python components: Documentation messages: 247184 nosy: docs@python, seirl priority: normal severity: normal status: open title: types.coroutines() idempotence documentation versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24692> _______________________________________

5 9

[issue17188] Document 'from None' in raise statement doc.
by Terry J. Reedy 30 May '17

30 May '17

New submission from Terry J. Reedy: Language manual, section 7.8. The raise statement has no mention of the 'from None' option. Indeed it says "if given, the second expression must be another exception class or instance", which would exclude None. Library manual, Ch 5. Built-in Exceptions, says ''' When raising a new exception (rather than using a bare raise to re-raise the exception currently being handled), the implicit exception context can be supplemented with an explicit cause by using from with raise: raise new_exc from original_exc The expression following from must be an exception or None. It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError, while leaving the old exception available in __context__ for introspection when debugging. ''' I am not sure how much should be copied over, but None should be at least mentioned and perhaps there should be a cross-reference. I am also not sure how much applies to 3.2, but there is no version-added or -changed note with the above. ---------- assignee: docs@python components: Documentation messages: 181939 nosy: docs@python, ncoghlan, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Document 'from None' in raise statement doc. versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17188> _______________________________________

13 34

[issue21056] csv documentation is incorrect
by NRGunby 23 May '17

23 May '17

New submission from NRGunby: The documentation for the csv reader objects next() method is incorrect. It states ' csvreader.next() Return the next row of the reader’s iterable object as a list, parsed according to the current dialect.' Either the documentation for DictReader objects needs to be be made separate from normal reader objects, or this needs to be amended to say ' csvreader.next() Return the next row of the reader’s iterable object as a list (if reader) or dict (if DictReader), parsed according to the current dialect. ' I observed this in the 2.7 online docs, found it to be the case in the 3.4 online docs as well, and haven't checked other versions but assume it's the case. ---------- assignee: docs@python components: Documentation messages: 214775 nosy: NRGunby, docs@python priority: normal severity: normal status: open title: csv documentation is incorrect type: behavior versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21056> _______________________________________

7 11

[issue20751] Misleading examples indDescriptor protocol documentation
by Jan Kaliszewski 20 May '17

20 May '17

New submission from Jan Kaliszewski: 1. One misleading detail in the descriptor protocol documentation for super bindings is that the following fragment of the http://docs.python.org/reference/datamodel.html#invoking-descriptors page: """ Super Binding If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__). """ ...introduces the method *call* (".m()") which AFAIK has nothing to do with the actual matter of the description (attribute resolution). Also, the "If *a* is an instance of super" fragment is strange, as *a* is not used in the following sentences at all. I believe the description should be: """ Super Binding If binding to a super instance, super(B, obj).x searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['x'].__get__(obj, obj.__class__). """ (using 'x' as the attribute name, as for the other kinds of binding). *** 2. Also, in some earlier fragment of the same page: """ Direct Call The simplest and least common call is when user code directly invokes a descriptor method: x.__get__(a). """ The call x.__get__(a) without the second argument seems to be wrong if __get__ is implemented according to the specification "object.__get__(self, instance, owner)" from the same documentation page. ---------- assignee: docs@python components: Documentation messages: 212035 nosy: docs@python, zuo priority: normal severity: normal status: open title: Misleading examples indDescriptor protocol documentation versions: 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/issue20751> _______________________________________

3 4

[issue11681] -b option undocumented
by Éric Araujo 13 May '17

13 May '17

New submission from Éric Araujo <merwok(a)netwok.org>: Python 2 has a -b command-line option which is undocumented. It is used by the warnings machinery to decide to warn about (-b) or raise an error (-bb) if someone uses str(bytes) or str(buffer) (explanation courtesy of grep and Python/pythonrun.c). ---------- assignee: docs@python components: Documentation keywords: easy messages: 132195 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: -b option undocumented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11681> _______________________________________

11 22

[issue15346] Tkinter dnd has no documentation
by Daniel Swanson 30 Apr '17

30 Apr '17

New submission from Daniel Swanson <popcorn.tomato.dude(a)gmail.com>: The title should be self explanatory. I needed Drag-and-drop for a project I was working on, (maybe I shouldn't be refering to it in the past tense as I haven't started yet) so I checked the documentation for tkinter and found: 3.3.0 b1 tkinter.dnd Drag-and-drop support for tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. 3.2.2 (and .2.3) tkinter.dnd Drag-and-drop support for tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. 2.7.3 Tkdnd Drag-and-drop support for Tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. I think that tkinter.dnd needs some documentation, whether or not it is replaced with Tk DND. ---------- assignee: docs@python components: Documentation messages: 165392 nosy: docs@python, weirdink13 priority: normal severity: normal status: open title: Tkinter dnd has no documentation versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15346> _______________________________________

4 10