Mailman 3 March 2017 - docs

small doc typo
by Sean Canavan April 14, 2017

April 14, 2017

Under https://docs.python.org/2/howto/argparse.html#introducing-optional-arguments "*So far we,* have been playing with positional arguments" should probably be "*So far we* have been playing with positional arguments" Cheers, Sean

2 1

[issue29791] print documentation: flush is also a keyword argument
by Lucio Ricardo Montero Valenzuela April 13, 2017

April 13, 2017

New submission from Lucio Ricardo Montero Valenzuela: In the print() function documentation (https://docs.python.org/3/library/functions.html#print), the first line says "Print objects to the text stream file, separated by sep and followed by end. sep, end and file, if present, must be given as keyword arguments.", but the function definition is said to be "print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)". Based on the Python user function definition grammar, the only way of passing an value to a non-star parameters that appear after a star-parameter is with the keyword (so the interpreter knows not to push the value into the star-parameter list/mapping). So the flush parameter can be set only naming explicitly the keyword 'flush' ¿Isn't it?. So the first line of the print() function documentation should say "Print objects to the text stream file, separated by sep and followed by end. sep, end, file and flush, if present, must be given as keyword arguments.". Flush is a new parameter, so maybe you forgot to update this line of the documentation to include it. Best regards. ---------- assignee: docs@python components: Documentation messages: 289411 nosy: Lucio Ricardo Montero Valenzuela, docs@python priority: normal severity: normal status: open title: print documentation: flush is also a keyword argument type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29791> _______________________________________

2 8

[issue26985] Information about CodeType in inspect documentation is outdated
by Xiang Zhang April 12, 2017

April 12, 2017

New submission from Xiang Zhang: Information about CodeType in inspect documentation is outdated. It lacks attributes: co_kwonlyargcount, co_freevars, co_cellvars. And co_flags lacks many more options. These also apply to the comments of inspect.iscode source code. ---------- assignee: docs@python components: Documentation messages: 265197 nosy: docs@python, xiang.zhang priority: normal severity: normal status: open title: Information about CodeType in inspect documentation is outdated versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26985> _______________________________________

2 13

[issue29521] Minor warning messages when compiling documentation
by Jim DeLaHunt April 10, 2017

April 10, 2017

New submission from Jim DeLaHunt: When I build the documentation on the current CPython code, there are various error and warning messages on the console. Here's what my build output looks like. I've marked the messages I'm concerned about with a numbered >>0>> prefix. ===== (beginning of output) % make html sphinx-build -b html -d build/doctrees -D latex_paper_size= . build/html Running Sphinx v1.5.2 loading pickled environment... done >>1>> WARNING: latex_preamble is deprecated. Use latex_elements['preamble'] instead. >>2>> WARNING: latex_paper_size is deprecated. Use latex_elements['papersize'] instead. building [mo]: targets for 0 po files that are out of date building [html]: targets for 466 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] whatsnew/changelog >>3>> ../../Misc/NEWS:659: WARNING: Inline emphasis start-string without end-string. >>4>> ../../Misc/NEWS:659: WARNING: Inline emphasis start-string without end-string. looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] whatsnew/index >>5>> /Users/jdlh/workspace/cpython_github/Doc/faq/windows.rst:303: WARNING: unknown option: -t generating indices... genindex py-modindex writing additional pages... download index >>6>> WARNING: Now base template defindex.html is deprecated. search opensearch copying images... [100%] using/win_installer.png copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded, 6 warnings. Build finished. The HTML pages are in build/html. ===== (end of output) This is observed when building documentation from branch master, commit b1dc6b6d5fa20f63f9651df2e7986a066c88ff7d . The build command is "cd Doc; make html". Warning >>6>> is the subject of http://bugs.python.org/issue29520 . It's harder to fix, and I won't address it here. The other five warnings are pretty easy to fix. Warnings >>1>>, >>2>> are Sphinx warnings about names used in Doc/conf.py , namely `latex_preamble` and `latex_paper_size`. There are straightforward changes to build a dict latex_elements{}, with keys 'preamble' and 'papersize'. It turns out that makefiles Doc/Makefile and Doc/make.bat also referred to `latex_paper_size`. Those references are rewritten as `latex_elements.papersize`, per Sphinx syntax for external names. Warnings >>3>>, >>4>> are Sphinx warnings about the text, in Misc/NEWS:661, ```is now of type "const char *" rather of "char *".``` Put a backslash in front of the '*', and the warning disappears. Warning >>5>> is a Sphinx warning about this text, in Doc/faq/windows.rst:303: If you suspect mixed tabs and spaces are causing problems in leading whitespace, run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to check a directory tree in batch mode. The notation :option:`-t` seems to need a corresponding ``.. cmdoption:: -t `` entry, perhaps in the same file. There is no such entry. It turns out that the -t option has no function in Python 3.6, maybe in all of 3.x. Python swallows the option but does nothing. Thus, instead of trying to make the reference to '-t' work, I decided to cut the whole phrase. This paragraph now reads, If you suspect mixed tabs and spaces are causing problems in leading whitespace, run ``Tools/Scripts/tabnanny.py`` to check a directory tree in batch mode. I am making a Pull Request with these fixes. I will shortly link to it from here. ---------- assignee: docs@python components: Documentation messages: 287480 nosy: JDLH, docs@python priority: normal severity: normal status: open title: Minor warning messages when compiling documentation type: compile error versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________

8 26

[issue29506] Incorrect documentation for the copy module
by Pedro April 9, 2017

April 9, 2017

New submission from Pedro: The docs for the copy module contain a bullet that says the following: "Because deep copy copies everything it may copy too much, e.g., even administrative data structures that should be shared even between copies." There should be a "not" between "should" and "be shared." I think the second "even" can be dropped, too. ---------- assignee: docs@python components: Documentation messages: 287367 nosy: docs@python, pgacv2 priority: normal severity: normal status: open title: Incorrect documentation for the copy module versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________

9 22

[issue29725] sqlite3.Cursor doesn't properly document "arraysize"
by Jürgen A. Erhard April 8, 2017

April 8, 2017

New submission from Jürgen A. Erhard: It's an attribute mentioned in fetchmany and fetchall, but it's not in the list with those two, but it should be, since the section says "A Cursor instance has the following attributes and methods." and it is an attribute. ---------- assignee: docs@python components: Documentation messages: 289023 nosy: docs@python, jae priority: normal severity: normal status: open title: sqlite3.Cursor doesn't properly document "arraysize" _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29725> _______________________________________

5 16

[issue26947] Documentation improvement needed
by mPython April 1, 2017

April 1, 2017

New submission from mPython: On following page: https://docs.python.org/3/glossary.html#term-hashable sentence "All of Python’s immutable built-in objects are hashable, while no mutable containers (such as lists or dictionaries) are." is not complete - probably a word "not" is needed on the end. ---------- assignee: docs@python components: Documentation messages: 264805 nosy: docs@python, mPython priority: normal severity: normal status: open title: Documentation improvement needed versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________

7 15

[issue26355] Emit major version based canonical URLs for docs
by Donald Stufft March 31, 2017

March 31, 2017

Changes by Donald Stufft <donald(a)stufft.io>: ---------- pull_requests: +1028 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26355> _______________________________________

1 0

[issue28929] Provide a link from documentation back to its source file
by Brett Cannon March 31, 2017

March 31, 2017

New submission from Brett Cannon: It would be great if we provided a link from a documentation page back to the source file that the page is produced from, e.g. have https://docs.python.org/3.6/library/abc.html provide a link to https://github.com/python/cpython/blob/3.6/Doc/library/abc.rst. ---------- assignee: docs@python components: Documentation messages: 282818 nosy: brett.cannon, docs@python priority: normal severity: normal stage: needs patch status: open title: Provide a link from documentation back to its source file type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28929> _______________________________________

5 28

[issue29000] Not matched behavior within printf style bytes formatting
by woo yoo March 31, 2017

March 31, 2017

New submission from woo yoo: Per the documentation,"The alternate form causes a leading octal specifier ('0o') to be inserted before the first digit", However the actual behavior didn't conform to the principle. Code: >>>b'%#07o' % 34 Output: b'0000o42' ---------- assignee: docs@python components: Documentation messages: 283485 nosy: docs@python, woo yoo priority: normal severity: normal status: open title: Not matched behavior within printf style bytes formatting versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29000> _______________________________________

5 9