Mailman 3 June 2016 - docs

[issue27215] Docstrings of Sequence and MutableSequence seems not right
by Raymond Hettinger 06 Jun '16

06 Jun '16

Raymond Hettinger added the comment: I think you're reading too much into the docs. Most useful classes provide a __new__ or __init__ to put data into instances. The docs are simply saying that that responsibility lies with the implementer rather than with the ABC. IMO, the docs are more useful as-is. Were we to accept the patch, it wouldn't be long before another user reported a bug saying that the implemented the other methods but the class didn't do anything useful. ---------- resolution: -> not a bug status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27215> _______________________________________

1 0

[issue27215] Docstrings of Sequence and MutableSequence seems not right
by Jelle Zijlstra 06 Jun '16

06 Jun '16

Jelle Zijlstra added the comment: The docstrings (at least in 3.6) say subclasses must override __new__ *or* __init__. However, I think this is wrong too. The following is a correct (if not very useful) implementation of Sequence: >>> import collections.abc >>> class MySequence(collections.abc.Sequence): ... def __getitem__(self, key): ... raise IndexError(key) ... def __len__(self): ... return 0 ... Other abc docstrings also don't claim that __init__ or __new__ must be implemented. The attached patch fixes the docstrings. ---------- keywords: +patch nosy: +Jelle Zijlstra Added file: http://bugs.python.org/file43245/issue27215.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27215> _______________________________________

1 0

[issue27188] sqlite3 execute* methods return value not documented
by Berker Peksag 06 Jun '16

06 Jun '16

Berker Peksag added the comment: Could you also change the function signatures from .. method:: execute(sql, [parameters]) to .. method:: execute(sql[, parameters]) and document that parameters should be list (or sequence or iterable -- I'm a the airport now so I can't check what is the correct term)? I'm not a native speaker but this sentence sounds a bit weird to me: This is a nonstandard shortcut that creates a cursor object by calling the cursor method, calls the cursor's :meth:`execute <Cursor.execute>` [...] Perhaps it can be changed to This is a nonstandard shortcut that creates a cursor object by calling the cursor's :meth:`execute <Cursor.execute>` method [...] Also, please change the following usages :meth:`execute <Cursor.execute>` with :meth:`~Cursor.execute` ---------- versions: +Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27188> _______________________________________

1 0

[issue27228] just for clearing: os.path.normpath("file://a") returns "file:/a"
by Arno-Can Uestuensoez 05 Jun '16

05 Jun '16

New submission from Arno-Can Uestuensoez: I am currently finishing a file system library and use 'os.path.normpath' for canonical input into match-operations. So already found Issue26329 - IEEE-1003.1-Chap 4.2 and written a comment. But I guess this issue should be handled seperately. Now have to deal by myself with the eventual prefix 'file://' for input, and guess it should be supported. I did not found a statement on this case, so issue this for clarification. The 'os.path.normpath' call simply replaces subsequent os.sep, when they are not leading as 1003.1 states. But how should the following examples be handled: file:////a => /a OR //a ??? file://///a => /a OK file:///a => /a OK ---------- assignee: docs@python components: Documentation messages: 267407 nosy: Fred Rolland, Winterflower, acue, docs@python, ebarry, lemburg, serhiy.storchaka priority: normal severity: normal status: open title: just for clearing: os.path.normpath("file://a") returns "file:/a" type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27228> _______________________________________

3 2

[issue27202] make doctest fails on 2.7 release notes
by Jelle Zijlstra 05 Jun '16

05 Jun '16

New submission from Jelle Zijlstra: Running `make doctest` in the Doc/ repository of master fails on the 2.7 release notes. This patch excludes these files from `make doctest`, because it doesn't seem worth it to try to get these running in Python 3. ---------- assignee: docs@python components: Documentation files: no27doctests.patch keywords: patch messages: 267190 nosy: Jelle Zijlstra, docs@python priority: normal severity: normal status: open title: make doctest fails on 2.7 release notes versions: Python 3.6 Added file: http://bugs.python.org/file43170/no27doctests.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27202> _______________________________________

5 13

Mention PYTHONFAULTHANDLER in the man page (issue 24459)
by berker.peksag＠gmail.com 05 Jun '16

05 Jun '16

http://bugs.python.org/review/24459/diff/17478/Misc/python.man File Misc/python.man (right): http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode434 Misc/python.man:434: Set the Python memory allocators and/or install debug hooks. I think we can make the PYTHONMALLOC documention a bit shorter. Detailed descriptions of memory allocations and debug hooks can be removed. It would more than enough to just say "these are the available memory allocatos and those are the available debug hooks". If people need more more information about what pymalloc or malloc_debug does they should read the online documentation. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode454 Misc/python.man:454: When Python is compiled in release mode, the default is "pymalloc". When This paragraph can stay. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode458 Misc/python.man:458: If Python is configured without "pymalloc" support, "pymalloc" and This paragraph can stay. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode469 Misc/python.man:469: This variable is ignored if the PYTHONMALLOC environment variable $PYTHONMALLOC http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode479 Misc/python.man:479: stored in a traceback of a trace. For example, "PYTHONTRACEMALLOC=1" .IB PYTHONTRACEMALLOC=1 http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode481 Misc/python.man:481: .IR tracemalloc.start() I think this is missing "documentation" here. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode488 Misc/python.man:488: dump the Python traceback. This is equivalent to -X "faulthandler" option. Move "This is equivalent ..." part to a new paragraph. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode490 Misc/python.man:490: If this environment variable is set, "sys.argv[0]" will be set to its value instead of the value got through the C runtime. Only works on Mac OS X. .IB sys.argv[0} http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode490 Misc/python.man:490: If this environment variable is set, "sys.argv[0]" will be set to its value instead of the value got through the C runtime. Only works on Mac OS X. Please also wrap these long lines. http://bugs.python.org/review/24459/diff/17478/Misc/python.man#newcode493 Misc/python.man:493: Setting these variables only has an effect in a debug build of Python, that is, if Python was configured with the --with-pydebug build option. fB\--with-pydebug\fP http://bugs.python.org/review/24459/

1 0

[issue17888] docs: more information on documentation team
by anatoly techtonik 05 Jun '16

05 Jun '16

New submission from anatoly techtonik: To help people understand that they can actually improve Python docs themselves, how about the following changes: http://docs.python.org/3/bugs.html - rename from "Reporting Bugs" to "Dealing with Bugs". Explain that sometimes fixing bug is easier than reporting, because it involves less time from all people in total. Link to step-by-step documentation for the process and include channel for proposals how to make the process more streamlined. Add links to archive and docs(a)python.org mailing list info http://mail.python.org/mailman/listinfo/docs On this info page make it clear that "Python documentation team" is not a team in common narrow sense, but a group of volunteers open for everybody. Either by providing a link to team page with listed members, or by replacing the text: - "Mailing list for the Python documentation team" + "Mailing list for people collaborating on Python docs" ---------- assignee: docs@python components: Documentation messages: 188218 nosy: docs@python, techtonik priority: normal severity: normal status: open title: docs: more information on documentation team _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17888> _______________________________________

9 13

[issue27203] Failing doctests in Doc/faq/programming.rst
by Senthil Kumaran 05 Jun '16

05 Jun '16

Senthil Kumaran added the comment: Thanks for the patch, Jelle Zijlstra. We don't have warnings in Doc/faq/programming.rst now, and this issue was specific to fix the doctests for it. I find it complete. Closing this issue. ---------- nosy: +orsenthil resolution: -> fixed stage: -> resolved status: open -> closed type: -> behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27203> _______________________________________

1 0

[issue27203] Failing doctests in Doc/faq/programming.rst
by Roundup Robot 05 Jun '16

05 Jun '16

Roundup Robot added the comment: New changeset fea14da8442d by Senthil Kumaran in branch '3.5': Issue27203 - Fix doctests Doc/faq/programming.rst. https://hg.python.org/cpython/rev/fea14da8442d New changeset 4a072fff6945 by Senthil Kumaran in branch 'default': [merge from 3.5] - Issue27203 - Fix doctests Doc/faq/programming.rst. https://hg.python.org/cpython/rev/4a072fff6945 ---------- nosy: +python-dev _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27203> _______________________________________

1 0

[issue16851] Hint about correct ismethod and isfunction usage
by Berker Peksag 05 Jun '16

05 Jun '16

Changes by Berker Peksag <berker.peksag(a)gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16851> _______________________________________

1 0