Mailman 3 October 2011 - docs

[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

[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

[issue13195] subprocess: args with shell=True is not documented on Windows
by anatoly techtonik Oct. 18, 2015

Oct. 18, 2015

New submission from anatoly techtonik <techtonik(a)gmail.com>: For UNIX, it is said that if shell=False then you need to pass `args` as a list (if you want to pass any parameters to executable). Is that true for Windows (and perhaps other platforms) as well? Again, for UNIX it is said that with shell=True, and args is a list - every item except the first one is an argument to the shell itself. Is it the same on Windows? It would be better to just give advice in `shell` parameter description to "pass args as a list with shell=False or else you'll lose params in Unix. If shell=True you need to pass args as a string, because list is needed only if you need to pass arguments to shell itself." ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 145662 nosy: docs@python, techtonik priority: normal severity: normal status: open title: subprocess: args with shell=True is not documented on Windows _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13195> _______________________________________

5 9

[issue8952] Doc/c-api/arg.rst: fix documentation of number formats
by STINNER Victor Oct. 14, 2015

Oct. 14, 2015

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex). I suppose that the following paragraph is also outdated: "It is possible to pass "long" integers (integers whose value exceeds the platform's :const:`LONG_MAX`) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary)." Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 107379 nosy: docs@python, haypo, mark.dickinson priority: normal severity: normal status: open title: Doc/c-api/arg.rst: fix documentation of number formats versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8952> _______________________________________

3 6

[issue13124] Add "Running a Build Slave" page to the devguide
by Eric Snow July 21, 2015

July 21, 2015

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: Here's a patch to add a page to the devguide on running a build slave. I copied pretty liberally from the wiki (http://wiki.python.org/moin/BuildBot). That page may or may not be up to date (I don't know), so the bulk of this new page may also be out of date... The current devguide buildbots page is oriented toward the use of buildbots in the dev process. In contrast, this new page is all about running one. I figured it is yet another easy way that people can contribute to Python. I didn't stick in the windows-specific buildbot info (http://wiki.python.org/moin/BuildbotOnWindows), but did link to the wiki page. I did include the info, as far as I understood it, from a recent python-dev thread (http://mail.python.org/pipermail/python-dev/2011-October/113935.html). I added a link to the devguide index page, but it may need to be shifted to the right spot (maybe right after "Running & Writing Tests"). I also renamed buildbots.rst to continuous_integration.rst (and updated reference accordingly). I want to be sure attribution is appropriate, regarding the text pulled from the wiki page and from the python-dev thread. Is linking to the thread sufficient? This is a rough stab (especially with the inclusion of the still-ongoing python-dev thread); but hopefully this gets a ball rolling and doesn't take much work to polish. :) ---------- assignee: docs@python components: Devguide, Documentation files: buildslaves.diff keywords: patch messages: 145120 nosy: brett.cannon, docs@python, eric.snow priority: normal severity: normal status: open title: Add "Running a Build Slave" page to the devguide type: feature request versions: Python 3.3 Added file: http://bugs.python.org/file23338/buildslaves.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13124> _______________________________________

8 21