Mailman 3 November 2015 - docs

[issue11253] autodocument first appearance of ctypes.wintypes constants
by anatoly techtonik 08 Nov '17

08 Nov '17

New submission from anatoly techtonik <techtonik(a)gmail.com>: I've just noticed that my application is incompatible with Python 2.5, because ctypes.wintypes is missing SHORT constants. However, I can't find the information when these symbols were introduced first. To prevent such confusion in future it would be nice to extract symbol information for each Python release and automatically include the version of the first appearance in documentation. ---------- assignee: docs@python components: Documentation messages: 128893 nosy: docs@python, techtonik priority: normal severity: normal status: open title: autodocument first appearance of ctypes.wintypes constants versions: Python 2.5, 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/issue11253> _______________________________________

6 7

[issue18669] curses.chgat() moves cursor, documentation says it shouldn't
by productivememberofsociety666 04 Nov '17

04 Nov '17

New submission from productivememberofsociety666: According to docs.python.org/2/library/curses.html#chgat (or any other version), curses.chgat() is not supposed to move the cursor at all. This is true if you don't give it x,y coordinates, but if you do, the cursor does in fact move to those coordinates, since it then uses C curses's mvchgat() internally and doesn't correct the position afterwards. See included file for demonstration: Expected output is: one two Actual output is: two Fix the documentation or fix the code :-) ---------- assignee: docs@python components: Documentation, Extension Modules files: chgat-bug.py messages: 194552 nosy: docs@python, productivememberofsociety666 priority: normal severity: normal status: open title: curses.chgat() moves cursor, documentation says it shouldn't type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file31175/chgat-bug.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18669> _______________________________________

6 10

[issue20064] PyObject_Malloc is not documented
by R. David Murray 31 Oct '17

31 Oct '17

New submission from R. David Murray: At least, a doc ref to :c:func:`PyObject_Malloc` does not turn into a link, and I can't find anything in the docs that it looks like it should link to. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 206910 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: PyObject_Malloc is not documented type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20064> _______________________________________

8 14

[issue17418] Documentation Bug
by Gurmeet Singh 28 Oct '17

28 Oct '17

New submission from Gurmeet Singh: Incompletely explained documentation at 2 places: 1. http://docs.python.org/3/library/functions.html#open The buffering argument is not correctly explained when setting to a positive argument in binary mode. 2. http://docs.python.org/3/library/os.html#os.open It is not very clear where to find descriptions of the arguments of this function. Where to find the required information and where to find C run-time documentation could be explained in following preferably: (Python/C API Reference Manual) http://docs.python.org/3/c-api/index.html and / or (The Python Standard Library) http://docs.python.org/3/library and / or (Python Runtime Services) http://docs.python.org/3/library/python.html A hyperlink may be added if so felt. ---------- assignee: docs@python components: Documentation messages: 184166 nosy: docs@python, gsingh priority: normal severity: normal status: open title: Documentation Bug versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________

4 6

[issue23702] docs.python.org/3/howto/descriptor.html still refers to "unbound methods"
by Paul Sokolovsky 25 Sep '17

25 Sep '17

New submission from Paul Sokolovsky: Under https://docs.python.org/3/howto/descriptor.html#functions-and-methods , there're several references to unbound methods (including in expected output from the interpreter). As known, unbound methods are gone in Python3, so seeing those are confusing. (I didn't sharply know that unbound methods are gone from Py3, so was pretty confused by the examples there, comparing them with actual output of Cpython 3.4). ---------- assignee: docs@python components: Documentation messages: 238468 nosy: docs@python, pfalcon priority: normal severity: normal status: open title: docs.python.org/3/howto/descriptor.html still refers to "unbound methods" versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23702> _______________________________________

8 15

[issue24243] behavior for finding an empty string is inconsistent with documentation
by swanson 18 Sep '17

18 Sep '17

New submission from swanson: Background: ----------- Perhaps this has been addressed elsewhere, but I couldn't find it. To me, semantically, the whole idea of finding nothing, whether in something or in nothing is complete and utter nonsense. I'm a fail-quickly, fail-loudly kind of guy, and I'd prefer that any attempt to find nothing would result in an exception being raised. But for whatever reason, the following behavior has long existed: >>> "".index("") == "A".index("") == 0 True >>> "" in "" and b"" in b"" and b"" in bytearray(b"") True >>> "" in "A" and b"" in b"A" and b"" in bytearray(b"A") True The Problem: ------------ The various string types (str, bytes, bytearray) all have the following functions: count, find, rfind, index, rindex Each of these functions accepts optional parameters "start" and "end". The documentation for each says something like "Optional arguments start and end are interpreted as in slice notation." This is not the case. On the one hand: >>> "".find("") == ""[0:0].find("") == "".find("", 0, 0) == 0 True Consistent so far, however: >>> "".find("") == ""[1:0].find("") == 0 and "".find("", 1, 0) == -1 True So, you see that 'start' and 'end' are NOT in all cases interpreted the same way as slicing. This problem has been around forever, affecting both Python 3 and 2, so I don't know how many people's code you'd break if you changed the behavior to make it consistent with the docs. But if it's not going to be changed, it should at least be a well-documented "feature" of the functions with a line or two of explanation in the relevant docs: https://docs.python.org/3/library/stdtypes.html#bytes-and-bytearray-operati… https://docs.python.org/3/library/stdtypes.html#string-methods The built-in types bytes, bytearray, and str also have the functions "startswith" and "endswith" that also take optional 'start' and 'end' arguments. The documentation does not specifically say (as for count, (r)find, and (r)index) that these are "interpreted as in slice notation". Instead, it says: "With optional start, test string beginning at that position. With optional end, stop comparing string at that position." That wording is equally confusing and erroneous. The natural interpretation of that would lead you to believe that, unlike slicing: "A".startswith("A",0,0) == True however it's really == False because the 'end' index is like slicing. Now, as to the interpretation of finding nothing, it's a mixed bag: For str: >>> "".startswith("",0,0) True >>> "".startswith("",1,0) True >>> "".endswith("",0,0) True >>> "".endswith("",1,0) True For bytes: (and the same for bytearray) >>> b"".startswith(b"",0,0) True >>> b"".startswith(b"",1,0) False >>> b"".endswith(b"",0,0) True >>> b"".endswith(b"",1,0) False ---------- assignee: docs@python components: Documentation messages: 243640 nosy: docs@python, swanson priority: normal severity: normal status: open title: behavior for finding an empty string is inconsistent with documentation type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24243> _______________________________________

7 11

[issue15472] Itertools doc summary table misdocuments some arguments
by Éric Araujo 16 Sep '17

16 Sep '17

New submission from Éric Araujo <merwok(a)netwok.org>: In the tables near the top of http://docs.python.org/library/itertools , some functions like cycle have an example that uses “seq”, which is interpreted as “sequence” but the functions do work with any iterable. ---------- assignee: docs@python components: Documentation messages: 166594 nosy: docs@python, eric.araujo, rhettinger priority: normal severity: normal status: open title: Itertools doc summary table misdocuments some arguments versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________

4 7

[issue15427] Describe use of args parameter of argparse.ArgumentParser.parse_args
by Steven Bethard 10 Sep '17

10 Sep '17

New submission from Steven Bethard <steven.bethard(a)gmail.com>: >From http://bugs.python.org/issue14191#msg155202: ArgumentParser.parse_args(args=None, namespace=None) ... However, nowhere is the args= parameter explained. One example is given at the end of 15.4.4.6 showing the use of args= which apparently accepts a list of parameters, similar to the positional list of parameters that are used in all the other examples. It might be nice to clarify that. ---------- assignee: docs@python components: Documentation messages: 166174 nosy: bethard, docs@python priority: normal severity: normal status: open title: Describe use of args parameter of argparse.ArgumentParser.parse_args type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15427> _______________________________________

5 10

[issue21818] cookielib documentation references Cookie module, not cookielib.Cookie class
by Angus Taggart 07 Sep '17

07 Sep '17

New submission from Angus Taggart: all the links to Cookie class in the cookielib documentation point to Cookie module. for example: CookieJar.set_cookie(cookie) Set a *Cookie*, without checking with policy to see whether or not it should be set. cookie in the documentation links to https://docs.python.org/2/library/cookie.html#module-Cookie cookie in the documentation should link to https://docs.python.org/2/library/cookielib.html#cookielib.Cookie ---------- assignee: docs@python components: Documentation messages: 221133 nosy: Ajtag, docs@python priority: normal severity: normal status: open title: cookielib documentation references Cookie module, not cookielib.Cookie class versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21818> _______________________________________

8 10

[issue24516] SSL create_default_socket purpose insufficiently documented
by Petr Messner 07 Sep '17

07 Sep '17

New submission from Petr Messner: Please, is it possible to put more information about the purpose parameter to the documentation of ssl.create_default_context()? It's not obvious that SERVER_AUTH should be used for client sockets and not server sockets. It took me a while to discover this, while all I was getting was only "SSLEOFError: EOF occurred in violation of protocol" (which is also not helpful). This is especially confusing, because OpenSSL uses serverAuth and clientAuth (for extendedKeyUsage configuration) in the exactly opposite meaning. ---------- assignee: docs@python components: Documentation messages: 245852 nosy: docs@python, messa priority: normal severity: normal status: open title: SSL create_default_socket purpose insufficiently documented type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24516> _______________________________________

3 5