Mailman 3 October 2012 - 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

[issue15984] Wrong documentation for PyUnicode_FromObject()
by Serhiy Storchaka April 15, 2016

April 15, 2016

New submission from Serhiy Storchaka: In the documentation it is written that PyUnicode_FromObject() is a shortcut for PyUnicode_FromEncodedObject(). But PyUnicode_FromObject() is not call PyUnicode_FromEncodedObject() direct nor indirect. PyUnicode_FromObject() works only with unicode and unicode subclass objects, PyUnicode_FromEncodedObject() is not works with unicode objects. ---------- assignee: docs@python components: Documentation messages: 170821 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Wrong documentation for PyUnicode_FromObject() versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15984> _______________________________________

11 26

[issue14456] Relation between threads and signals unclear
by Sven Marnach April 11, 2016

April 11, 2016

New submission from Sven Marnach <sven(a)marnach.net>: The documentation of the 'signal' module states on the one hand [T]he main thread will be the only one to receive signals (this is enforced by the Python signal module, even if the underlying thread implementation supports sending signals to individual threads). On the other hand, it provides the function 'pthread_kill()': Send the signal signum to the thread thread_id, another thread in the same process as the caller. The signal is asynchronously directed to thread. These two passages are in contradiction to each other. The documentation also states that only the main thread can set signal handlers -- if this is true, it is utterly unclear how sending signals to other threads is useful. Probably the documentation wasn't fully updated when the above function was introduced. ---------- assignee: docs@python components: Documentation messages: 157156 nosy: docs@python, smarnach priority: normal severity: normal status: open title: Relation between threads and signals unclear versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14456> _______________________________________

4 6

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

April 10, 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

[issue15117] Please document top-level sqlite3 module variables
by wchlm March 27, 2016

March 27, 2016

New submission from wchlm <shenkin(a)gmail.com>: sqlite3 top-level variables, such as version, sqlite_version, version_info, and sqlite_version_info are all useful for Python users of the module -- even essential at times. Yet there is no mention of them in the Py 2.7.3 documentation. dir(sqlite3) reveals a longer list. It would be good if someone with a deeper knowledge of the module could assemble a list of useful items and add them to the sqlite3 documentation. ---------- assignee: docs@python components: Documentation messages: 163285 nosy: docs@python, shenkin priority: normal severity: normal status: open title: Please document top-level sqlite3 module variables versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15117> _______________________________________

4 3

[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

[issue15608] Improve socketserver doc
by Terry J. Reedy Feb. 19, 2016

Feb. 19, 2016

New submission from Terry J. Reedy: On Windows, 3.3 socketserver defines 12 classes in 3 categories: servers, server mixins, and handlers. (At least, these are the one listed with dir(socketserver). Only BaseServer is indexed. I think all should be. There are also a couple of text issues. BaseServer - indexed, doc is 20.19.2. Server Objects TCPServer - mentioned in diagram and text of 20.19.1 UDPServer - ditto (I presume *nix version have unixxxx classes also) ForkingMixIn - text of 20.19.1 ThreadingMixIn - ditto ForkingTCPServer ForkingUDPServer ThreadingTCPServer ThreadingUDPServer Text says "Forking and threading versions of each type of server can be created using the ForkingMixIn and ThreadingMixIn mix-in classes. For instance, a threading UDP server class is created as follows: class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass The mix-in class must come first, since it overrides a method defined in UDPServer." "can be" means to me that user must create these. I am guessing that pre-defining them was added later. So text should change to 'have been'. The pre-created combinations should be listed. The last sentence could then say "Thhe mix-in class comes first since it overrides...". --- BaseRequestHandler This is documented in 20.19.2 RequestHandler Objects. But instead of starting with something like class socketserver.BaseRequestHandler This is the superclass of all RequestHandler objects. It defines the interface, given below, but does not implement most of the methods, which is done in subclasses. A new instance of the subclass is created for each request. analogous to the initial entry in 20.19.1, 20.19.2 starts with "The request handler class must define a new handle() method, and can override any of the following methods. A new instance is created for each request. I suggest that this be replaced with a standard class entry like the one above. If done, I resume the "RequestHandler" method prefix should be "BaseRequestHandler". StreamRequestHandler - these two are described in a paragraph DatagramRequestHandler - after the handle method entry --- In summary: 1. index all classes to point to locations indicated above. 2. state that mixin combinations are pre-defined. 3. give BaseRequestHandler a proper entry. 4. revise above as needed for *nix. 5. optionally adjust as needed for 2.7. ---------- assignee: docs@python components: Documentation messages: 167825 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Improve socketserver doc versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15608> _______________________________________

4 8

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

Feb. 8, 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