Mailman 3 August 2013 - docs

[issue10438] list an example for calling static methods from WITHIN classes
by Ian 12 Jul '17

12 Jul '17

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all. So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method". I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete. ---------- assignee: docs@python components: Documentation messages: 121314 nosy: docs@python, ifreecarve priority: normal severity: normal status: open title: list an example for calling static methods from WITHIN classes type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10438> _______________________________________

7 19

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

[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

[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

[issue15369] pybench and test.pystone poorly documented
by Florent Xicluna 31 Mar '17

31 Mar '17

New submission from Florent Xicluna <florent.xicluna(a)gmail.com>: The benchmarking tools "pystones" and "pybench" which are shipped with the Python standard distribution are not documented. The only information is in the what's-new for Python 2.5: http://docs.python.org/dev/whatsnew/2.5.html?highlight=pybench#new-improved… IMHO, they should be mentioned somewhere in the HOWTOs, the FAQ or the standard library documentation ("Development Tools" or "Debugging and Profiling") ---------- assignee: docs@python components: Benchmarks, Documentation messages: 165603 nosy: docs@python, flox priority: normal severity: normal status: open title: pybench and test.pystone poorly documented type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15369> _______________________________________

7 17

[issue16011] "in" should be consistent with return value of __contains__
by Neal Parikh 29 Mar '17

29 Mar '17

New submission from Neal Parikh: The Python 2.7.3 documentation says the following about defining __contains__: "Called to implement membership test operators. Should return true if item is in self, false otherwise. For mapping objects, this should consider the keys of the mapping rather than the values or the key-item pairs." This suggests that while you should return True/False, you don't need to. Also, the documentation doesn't say that if you return a value other than True or False, it will silently coerce other values to be True or False when you use "in". For example: >>> class Foo(object): ... def __contains__(self, item): return 42 ... >>> foo = Foo() >>> 3 in foo True >>> foo.__contains__(3) 42 When __contains__ is defined, "in" should return whatever __contains__ returns, even if this value is neither True nor False. That would be consistent with, for example, the comparison operators: You can return anything from __lt__ and "x < 4" will correctly pass along that value regardless of what it is. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 171085 nosy: docs@python, nparikh priority: normal severity: normal status: open title: "in" should be consistent with return value of __contains__ type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16011> _______________________________________

10 25

[issue17003] Unification of read() and readline() argument names
by Serhiy Storchaka 07 Mar '17

07 Mar '17

New submission from Serhiy Storchaka: read() and readline() optional parameter which limit the amount of read data has different names in different classes. All this classes mimic (less or more) io classes. Keyword parameter name is a part of method specification. Therefore it will be good made all read() arguments names the same and all readline() arguments names the same (and be consistent with documentation and C implementation). At least we should choose most consistent name for new implementations. If existent C implementation of some method doesn't support keyword argument (all _io classes) or argument names in C and Python implementations are different then we are free to change this name without breaking existing code. For example, read()'s parameter named as: "n" in _pyio, zipfile, and io documentation; "size" in gzip, bz2, imaplib, tarfile, codecs, mailbox; "len" in ssl; "wtd" or "totalwtd" in binhex; "amt" in http/client; "chars" in codecs; "buffersize" in os. readline()'s parameter named as: "limit" in _pyio, zipfile, and io documentation; "size" in gzip, bz2, codecs, mailbox, lzma. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 180298 nosy: benjamin.peterson, christian.heimes, docs@python, hynek, pitrou, serhiy.storchaka, stutzbach priority: normal severity: normal status: open title: Unification of read() and readline() argument names type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________

5 10

[issue18423] Document limitations on -m
by andrew cooke 23 Feb '17

23 Feb '17

New submission from andrew cooke: Apparently the limited support for -m is standard behaviour - see http://bugs.python.org/issue18422 - but it's not documented at http://docs.python.org/3/using/cmdline.html#cmdoption-m That should say, somewhere, that it only applies to leaf modules and packages. ---------- assignee: docs@python components: Documentation messages: 192804 nosy: acooke, docs@python priority: normal severity: normal status: open title: Document limitations on -m _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18423> _______________________________________

6 6

[issue15657] Error in Python 3 docs for PyMethodDef
by Sandro Tosi 22 Feb '17

22 Feb '17

New submission from Sandro Tosi: Hello, it has been reported at http://mail.python.org/pipermail/docs/2012-April/008215.html but given it raises some question whether it's a bug in the doc or in the code, i'd rather report the issue here and hear what other think: >>> In the Python 3.2.2 documentation (and earlier Python 3 versions), in the Python/C API Reference Manual, chapter Object Implementation Support, the documentation for PyMethodDef says: The ml_flags field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention. Of the calling convention flags, only METH_VARARGS and METH_KEYWORDS can be combined (but note that METH_KEYWORDS alone is equivalent to METH_VARARGS | METH_KEYWORDS). The bit in the parenthetical is incorrect. If you take a look at PyCFunction_Call in Objects/methodobject.c, you will find a switch for METH_VARARGS | METH_KEYWORDS, but no switch for METH_KEYWORDS. Hence, using METH_KEYWORDS will land you with a SystemError that complains about METH_OLDARGS. This is either a bug in the documentation, or a bug in Python. In this case, since the code has persisted through three major revisions of Python 3, I suggest that the bug _is_ in the documentation (whether it should be or not), since changing the code for this at this late date means a programmer has to use METH_VARARGS | METH_KEYWORDS anyway for compatibility. It may be work pointing out specifically in the documentation that just using METH_KEYWORDS will not work. <<< ---------- assignee: docs@python components: Documentation messages: 168226 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Error in Python 3 docs for PyMethodDef versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________

12 18