Mailman 3 August 2013 - docs

[issue17888] docs: more information on documentation team
by anatoly techtonik June 5, 2016

June 5, 2016

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

[issue13784] Documentation of xml.sax.xmlreader: Locator.getLineNumber() and Locator.getColumnNumber()
by patrick vrijlandt June 2, 2016

June 2, 2016

New submission from patrick vrijlandt <patrick.vrijlandt(a)gmail.com>: Problem: Locator methods return the location where the event starts, not where it ends. Locator line numbers start at 1, Locator column numbers can be 0. Proposal: Adapt documentation. >From the docs: Instances of Locator provide these methods: Locator.getColumnNumber() Return the column number where the current event ends. Locator.getLineNumber() Return the line number where the current event ends My Test: import xml.sax data = b"""<main> <sub attr="1" id="name" > <subsub /> </sub> </main>""" class MyHandler(xml.sax.handler.ContentHandler): def startElement(self, name, attrs): if name == "sub": print("open", name, self._locator.getLineNumber(), self._locator.getColumnNumber()) def endElement(self, name): if name == "sub": print("close", name, self._locator.getLineNumber(), self._locator.getColumnNumber()) xml.sax.parseString(data, MyHandler()) Output: open sub 2 4 close sub 7 4 ---------- assignee: docs@python components: Documentation, XML messages: 151247 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: Documentation of xml.sax.xmlreader: Locator.getLineNumber() and Locator.getColumnNumber() type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13784> _______________________________________

5 4

[issue18384] Add devhelp build instructions to the documentation makefile
by Balthazar Rouberol June 2, 2016

June 2, 2016

New submission from Balthazar Rouberol: The documentation makefile is missing support for Devhelp. The supplied patch fixes this for the Python 3 branch. It also edits the ouput of the sphinx build to change the name of the devhelp project. This is needed to be able to have both versions of documentation (py2 & py3) displayed in Devhelp. This is useful if developers need to access documentation for both versions, such as both maintaining a Python2 project and starting a new project in Python3. This has been patched in some distributions downstream, but would be nice to have patched upstream. See: https://bugs.launchpad.net/ubuntu/+source/devhelp/+bug/787039 ---------- assignee: docs@python components: Documentation files: devhelp-build-py3.patch keywords: patch messages: 192457 nosy: brouberol, docs@python priority: normal severity: normal status: open title: Add devhelp build instructions to the documentation makefile type: enhancement versions: Python 3.5 Added file: http://bugs.python.org/file30823/devhelp-build-py3.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18384> _______________________________________

4 7

[issue12243] getpass.getuser works on OSX
by Bryce Verdier June 2, 2016

June 2, 2016

New submission from Bryce Verdier <bryceverdier(a)gmail.com>: In the docs for getpass: http://docs.python.org/release/2.6.6/library/getpass.html (as an example). It hints that getuser() doesn't work on OSX. I tried this out and it works fine for python 2.6 on 10.6. I have included a patch for this. I believe the cleanest way to handle this is to remove the "Availability" entry as it's no longer necessary. ---------- assignee: docs@python components: Documentation files: getuser.patch keywords: patch messages: 137483 nosy: docs@python, louiscipher priority: normal severity: normal status: open title: getpass.getuser works on OSX versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file22222/getuser.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12243> _______________________________________

7 12

[issue17383] Error in documentation /2/tutorial/modules.html#more-on-modules
by Piotr Kuchta June 1, 2016

June 1, 2016

New submission from Piotr Kuchta: In the 2.7 tutorial, chapter on modules: http://docs.python.org/2/tutorial/modules.html#more-on-modules I think the last sentence in this paragraph is incorrect: "Modules can import other modules. It is customary but not required to place all import statements at the beginning of a module (or script, for that matter). The imported module names are placed in the importing module’s global symbol table." This is not true: >>> def foo(): import sys ... >>> foo() >>> sys.path Traceback (most recent call last): File "<stdin>", line 1, in <module> NameError: name 'sys' is not defined ---------- assignee: docs@python components: Documentation messages: 183715 nosy: Piotr.Kuchta, docs@python priority: normal severity: normal status: open title: Error in documentation /2/tutorial/modules.html#more-on-modules versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

7 15

[issue9911] doc copyedits
by DSM May 26, 2016

May 26, 2016

New submission from DSM <dsm001(a)users.sourceforge.net>: Various typo fixes for the docs. As usual, I left historical documents alone (except for 3.1 whatsnew: fixed the spelling of Jack Diederich's name). Fixing ~30 means I probably introduced ~3 problems of my own, but that should still be a net win.. Patch against py3k r84944. ---------- assignee: docs@python components: Documentation files: typos.patch keywords: patch messages: 117052 nosy: docs@python, dsm001 priority: normal severity: normal status: open title: doc copyedits versions: Python 3.3 Added file: http://bugs.python.org/file18947/typos.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9911> _______________________________________

3 2

[issue16509] sqlite3 docs do not explain check_same_thread
by Daniel Micay May 25, 2016

May 25, 2016

New submission from Daniel Micay: The sqlite3 documentation now includes a Multithreading section explaining issues with older sqlite versions, but still doesn't directly cover disabling check_same_thread beyond listing it as a possible parameter. As far as I can tell, reusing sqlite connections in different threads (such as from a pool) is safe, as long as no attempt is made to use them from multiple threads with no locking. ---------- assignee: docs@python components: Documentation messages: 175946 nosy: docs@python, strcat priority: normal severity: normal status: open title: sqlite3 docs do not explain check_same_thread type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16509> _______________________________________

6 7

[issue18531] Undocumented different between METH_KEYWORDS and **kws
by Barry A. Warsaw May 16, 2016

May 16, 2016

New submission from Barry A. Warsaw: A colleague discovered an interesting implementation different between C-defined functions and Python-defined functions called with **kws arguments. He tried to do this: >>> from collections import defaultdict >>> '{foo}{bar}'.format(**defaultdict(str)) '' He wondered how this could work, especially given: >>> def what(**kws): ... print(type(kws), repr(kws)) ... >>> what(**defaultdict(str)) <class 'dict'> {} The Language Reference clearly states that when what() is called, a new dictionary is create, which is populated by keyword arguments not consumed by positional args. http://docs.python.org/3/reference/compound_stmts.html#function-definitions http://docs.python.org/3/reference/expressions.html#calls What isn't described is the behavior when the function is defined in C using METH_KEYWORDS. In that case, the object passed through the ** argument is passed unscathed to the underlying methodobject defined to take METH_KEYWORDS. str.format() is of the latter type so it gets the actual defaultdict. what() of course gets the defined behavior. It would be nice if the implementation details of the function did not leak into this behavior, but this is admittedly a corner case of the CPython implementation. I haven't checked any of the alternative implementations to see what they do. My guess is that CPython won't change for practical and backward compatibility reasons, thus I've opened this issue as a documentation bug. At the very least, an implementation note in the Language Reference should be added. ---------- assignee: docs@python components: Documentation messages: 193559 nosy: barry, docs@python priority: normal severity: normal status: open title: Undocumented different between METH_KEYWORDS and **kws versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18531> _______________________________________

6 18

[issue11643] Use |version| instead of X.Y in the doc
by Éric Araujo May 7, 2016

May 7, 2016

New submission from Éric Araujo <merwok(a)netwok.org>: Some files like site.rst use “X.Y” to refer to the Python version, but Sphinx helpfully provides a |version| construct that can be replaced by the current version at build time. ---------- assignee: docs@python components: Documentation keywords: easy messages: 131816 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Use |version| instead of X.Y in the doc versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________

8 15

[issue18841] math.isfinite fails with Decimal sNAN
by Steven D'Aprano May 6, 2016

May 6, 2016

New submission from Steven D'Aprano: math.isfinite currently raises ValueError when given a Decimal sNAN (signalling NAN). I've run into a situation where I'm calling isfinite() on a numeric value which may be a Decimal sNAN, and it would be nice if it returned False. On the other hand, see the discussion on issue 15544, which possibly leads to the conclusion that raising ValueError is the right thing to do. http://bugs.python.org/issue15544 Either way, behaviour should be documented. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 196213 nosy: docs@python, stevenjd priority: normal severity: normal status: open title: math.isfinite fails with Decimal sNAN type: behavior versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18841> _______________________________________

6 5