Mailman 3 November 2015 - docs

[issue24136] document PEP 448
by Benjamin Peterson 12 Jun '16

12 Jun '16

New submission from Benjamin Peterson: PEP 448 has been implemented (#2292), but the documentation hasn't been updated. Updating the documentation will improve looking through Doc/reference/* and making sure the documentation (and grammar) for calls and assignments is updated for PEP 448's new syntax. I'm marking this as "easy" because it might be a good first bug. ---------- assignee: docs@python components: Documentation keywords: easy messages: 242668 nosy: benjamin.peterson, docs@python priority: high severity: normal stage: needs patch status: open title: document PEP 448 type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24136> _______________________________________

12 27

[issue15476] Add "code object" to glossary
by Chris Jerdonek 09 Jun '16

09 Jun '16

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: This issue is to add "code object" to the documentation glossary, as discussed in issue 15457 regarding the documentation around generators. This can be a minimal entry that links to the details here, for example-- http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy specifically: http://docs.python.org/dev/reference/datamodel.html#index-52 ---------- assignee: docs@python components: Documentation keywords: easy messages: 166633 nosy: cjerdonek, docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Add "code object" to glossary type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________

8 19

[issue21593] Clarify re.search documentation first match
by Joshua Landau 08 Jun '16

08 Jun '16

New submission from Joshua Landau: The documentation for re.search does not state that it returns the first match. This should be added, or a clarification added if this is implementation-defined. https://docs.python.org/3/library/re.html#re.search --- See also http://stackoverflow.com/questions/23906400/is-regular-expression-search-gu… ---------- assignee: docs@python components: Documentation messages: 219270 nosy: Joshua.Landau, docs@python priority: normal severity: normal status: open title: Clarify re.search documentation first match versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21593> _______________________________________

5 8

socket.fileno() documentation
by Vlado Potisk 06 Jun '16

06 Jun '16

I might be wrong but in my opinion the socket library documentation is not clear enough regarding the behaviour of the fileno() method in a case of a failure. In the Python 3.2 socket library documentation there is: ---- exception socket.error A subclass of IOError, this exception is raised for socket-related errors. ----- socket.close() Close the socket. All future operations on the socket object will fail. ---- socket.fileno() Return the socket’s file descriptor (a small integer). ---- Based on the information quoted above, I wrote a test if a socket is active or if it has been closed already: try: sock.fileno() except socket.error: return False return True But is doesn't work. I have found out that fileno() returns -1 on a closed socket. Replacing fileno() with e.g. getsockname() fixes the code. It looks like a fileno's failure - unlike to getsockname's failure - is not expressed by raising an exception, but by returning -1. However this seems to be not documented and that's why I'm unsure if I may rely on this.

9 8

[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

[issue22797] urllib.request.urlopen documentation falsely guarantees that a URLError will be raised on errors
by Joshua Chin 04 Jun '16

04 Jun '16

New submission from Joshua Chin: The documentation for urlopen states that it "Raises URLError on errors." However, urlopen can raise a ValueError. In fact, test_urllib. urlopen_FileTests.test_relativelocalfile specifically checks if urlopen raises a ValueError. I suggest removing the guarantee from the documentation. ---------- assignee: docs@python components: Documentation files: urlopen_doc.patch keywords: patch messages: 230640 nosy: Joshua.Chin, docs@python, orsenthil priority: normal severity: normal status: open title: urllib.request.urlopen documentation falsely guarantees that a URLError will be raised on errors type: behavior versions: Python 3.4 Added file: http://bugs.python.org/file37129/urlopen_doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22797> _______________________________________

4 9

[issue13784] Documentation of xml.sax.xmlreader: Locator.getLineNumber() and Locator.getColumnNumber()
by patrick vrijlandt 02 Jun '16

02 Jun '16

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 01 Jun '16

01 Jun '16

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

[issue20693] Sidebar scrolls down 2x as fast as page content
by Nick Timkovich 01 Jun '16

01 Jun '16

New submission from Nick Timkovich: When scrolling down in the Python 3.4 docs (e.g. http://docs.python.org/3.4/library/index.html ) the Sphinx sidebar's top value increases twice as fast as the user moves down the page, resulting in it "running away". I don't know sufficient JS to identify the problem, but I'm guessing it's somewhere in the sidebar.js:scroll_sidebar() function or whatever might configure it. (apologies, I *think* I may have sent a similar mail to the docs list already) ---------- assignee: docs@python components: Documentation files: py34sidebar.png messages: 211675 nosy: docs@python, nicktimko priority: normal severity: normal status: open title: Sidebar scrolls down 2x as fast as page content type: behavior versions: Python 3.4 Added file: http://bugs.python.org/file34149/py34sidebar.png _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20693> _______________________________________

8 11

[issue12243] getpass.getuser works on OSX
by Bryce Verdier 01 Jun '16

01 Jun '16

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