Mailman 3 February 2012 - docs

[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

[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

[issue9014] Incorrect documentation of the PyObject_HEAD macro
by Renato Cunha April 19, 2016

April 19, 2016

New submission from Renato Cunha <renato(a)renatocunha.com>: PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes. PyObject_HEAD is actually defined as #define PyObject_HEAD PyObject ob_base; with PyObject defined as typedef struct _object { _PyObject_HEAD_EXTRA Py_ssize_t ob_refcnt; struct _typeobject *ob_type; } PyObject; (The PyTRACE_REFS discussion is still valid, though.) Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members. ---------- assignee: docs@python components: Documentation messages: 107953 nosy: docs@python, trovao priority: normal severity: normal status: open title: Incorrect documentation of the PyObject_HEAD macro type: behavior versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9014> _______________________________________

7 9

[issue10289] Document magic methods called by built-in functions
by Éric Araujo April 9, 2016

April 9, 2016

New submission from Éric Araujo <merwok(a)netwok.org>: At the top of Doc/library/functions.rst, which documents built-in functions like abs, getattr or hash, a comment reads “document all delegations to __special__ methods”. Some functions are already good: enumerate for instance does link to the definition of iterator and hints about the __next__ method, format points to __format__, etc. They can serve as example for how to add links (in plain text and in the global index). ---------- assignee: docs@python components: Documentation messages: 120189 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Document magic methods called by built-in functions versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10289> _______________________________________

10 14

[issue13354] tcpserver should document non-threaded long-living connections
by Bas Wijnen Feb. 20, 2016

Feb. 20, 2016

New submission from Bas Wijnen <wijnen(a)debian.org>: http://docs.python.org/py3k/library/socketserver.html says: The solution is to create a separate process or thread to handle each request; the ForkingMixIn and ThreadingMixIn mix-in classes can be used to support asynchronous behaviour. There is another way, which doesn't bring multi-threading hell over you: keep a copy of the file descriptor and use it when events occur. I recall that this suggestion used to be in the documentation as well, but I can't find it anymore. It would be good to add this suggestion to the documentation. However, there is a thing you must know before you can use this approach: tcpserver calls shutdown() on the socket when handle() returns. This means that the network connection is closed. Even dup2() doesn't keep it open (it lets you keep a file descriptor, but it returns EOF). The solution for this is to override shutdown_request of your handler to only call close_request (or not call anything at all) for sockets which must remain open. That way, as long as there is a reference to the socket, the network connection will not be shut down. Optionally the socket can be shutdown() explicitly when you're done with the connection. Something like the paragraph above would be useful in the documentation IMO. ---------- assignee: docs@python components: Documentation messages: 147147 nosy: docs@python, shevek priority: normal severity: normal status: open title: tcpserver should document non-threaded long-living connections type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13354> _______________________________________

3 7

[issue8810] TZ offset description is unclear in docs
by Alexander Belopolsky Feb. 7, 2016

Feb. 7, 2016

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: >From <http://docs.python.org/dev/py3k/library/datetime.html#datetime.tzinfo.utcof…>: """ tzinfo.utcoffset(self, dt) Return offset of local time from UTC, in minutes east of UTC. """ This suggests that the return value is an integer representing the number of minutes. It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence. I suggest s/in minutes east of UTC/as a timedelta object/. I think "east of UTC" is redundant given the next sentence, "If local time is west of UTC, this should be negative", but that can also be reworded for clarity as "The offset for timezones west of UTC is negative, and for those east of UTC is positive." ---------- assignee: docs@python components: Documentation keywords: easy messages: 106371 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: TZ offset description is unclear in docs versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8810> _______________________________________

6 19

[issue12484] The Py_InitModule functions no longer exist, but remain in the docs
by Alejandro Santos Dec. 27, 2015

Dec. 27, 2015

New submission from Alejandro Santos <alejolp(a)alejolp.com>: While the "Py_InitModule" does not exists on Py3k it is still mentioned on the docs: http://docs.python.org/py3k/extending/extending.html#keyword-parameters-for… http://docs.python.org/py3k/extending/windows.html#a-cookbook-approach http://docs.python.org/py3k/faq/extending.html#what-does-systemerror-pyimpo… ---------- assignee: docs@python components: Documentation messages: 139728 nosy: alejolp, docs@python priority: normal severity: normal status: open title: The Py_InitModule functions no longer exist, but remain in the docs versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12484> _______________________________________

8 16

[issue10942] xml.etree.ElementTree.tostring returns type bytes, expected type str
by J_Tom_Moon_79 Nov. 26, 2015

Nov. 26, 2015

New submission from J_Tom_Moon_79 <jtm.moon.forum.user+python(a)gmail.com>: method xml.etree.ElementTree.tostring from module returns type bytes. The documentation reads """Returns an encoded string containing the XML data.""" (from http://docs.python.org/py3k/library/xml.etree.elementtree.html#xml.etree.El… as of 2011-01-18) ======================================================= Here is a test program: ------------------------------------------------------- #!/usr/bin/python # created for python 3.1 import sys print(sys.version) # for help verifying version tested from xml.etree import ElementTree sampleinput = """<?xml version="1.0"?><Hello></Hello>""" xmlobj = ElementTree.fromstring(sampleinput) type(xmlobj) xmlstr = ElementTree.tostring(xmlobj,'utf-8') print("xmlstr value is '", xmlstr, "'", sep="") print("xmlstr type is '", type(xmlstr), "'", sep="") ------------------------------------------------------- test program output: ------------------------------------------------------- 3.1.3 (r313:86834, Nov 27 2010, 18:30:53) [MSC v.1500 32 bit (Intel)] xmlstr value is 'b'<Hello />'' xmlstr type is '<class 'bytes'>' ======================================================= This cheap "fix" for this bug may be simply be a change in documentation. However, a method called "tostring" really should return something nearer to the built-in str. ---------- assignee: docs@python components: Documentation, XML messages: 126506 nosy: JTMoon79, docs@python priority: normal severity: normal status: open title: xml.etree.ElementTree.tostring returns type bytes, expected type str type: behavior versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10942> _______________________________________

4 5

[issue13275] Recommend xml.etree for XML processing
by Alexey Shamrin Nov. 26, 2015

Nov. 26, 2015

New submission from Alexey Shamrin <shamrin(a)gmail.com>: There are many libraries in Python stdlib [1] xml.dom xml.dom.minidom xml.dom.pulldom xml.sax xml.etree Tutorial mentions xml.dom and xml.sax. [2] In my experience xml.etree is the best library to quickly load some xml and mess with it. It would be nice to recommend people xml.etree in the tutorial [2] and in the beginning of section 19, "Structured Markup Processing Tools". [1] [1]: http://docs.python.org/library/markup.html [2]: http://docs.python.org/tutorial/stdlib.html#batteries-included ---------- assignee: docs@python components: Documentation messages: 146484 nosy: ash, docs@python priority: normal severity: normal status: open title: Recommend xml.etree for XML processing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13275> _______________________________________

8 11

[issue12300] Document pydoc.help
by Éric Araujo Nov. 3, 2015

Nov. 3, 2015

New submission from Éric Araujo <merwok(a)netwok.org>: The only public function in pydoc is help, and it’s not listed in the module docs. The existing doc in library/functions could be moved to library/pydoc. See also #12299. ---------- assignee: docs@python components: Documentation messages: 138002 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: Document pydoc.help versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12300> _______________________________________

3 4