Mailman 3 August 2013 - docs

[issue13354] tcpserver should document non-threaded long-living connections
by Bas Wijnen 20 Feb '16

20 Feb '16

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 19 Feb '16

19 Feb '16

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 08 Feb '16

08 Feb '16

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

[issue16731] xxlimited/xxmodule docstrings ambiguous
by Daniel Shahaf 28 Jan '16

28 Jan '16

New submission from Daniel Shahaf: Tweak the docstrings of xxmodule and xxlimited to clarify the difference between them (as derived from setup.py). While at it also add a defensive coding guard to xxlimited to ensure it remains Py_LIMITED_API-safe. ---------- assignee: docs@python components: Documentation, Extension Modules files: xxdocstrings.diff keywords: patch messages: 177774 nosy: danielsh, docs@python priority: normal severity: normal status: open title: xxlimited/xxmodule docstrings ambiguous versions: Python 3.4 Added file: http://bugs.python.org/file28367/xxdocstrings.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________

5 7

[issue18620] multiprocessing page leaves out important part of Pool example
by Chris Curvey 21 Jan '16

21 Jan '16

New submission from Chris Curvey: on http://docs.python.org/2/library/multiprocessing.html, there is a bit about how to use a Pool properly, which looks like this pool = Pool(processes=4) # start 4 worker processes result = pool.apply_async(f, [10]) What this neglects to mention is that only one process will get any of the work. If you really want four processes in the pool to work, you have to call apply_async four times. For example: results = [] pool = Pool(processes=4) for i in xrange(4): results.append(pool.apply_async(f, [10])) hat tip to http://stackoverflow.com/questions/12483512/python-multiprocessing-apply-as… ---------- assignee: docs@python components: Documentation messages: 194115 nosy: Chris.Curvey, docs@python priority: normal severity: normal status: open title: multiprocessing page leaves out important part of Pool example type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18620> _______________________________________

7 12

[issue16544] Add external link to ast docs
by Andrew Svetlov 07 Jan '16

07 Jan '16

New submission from Andrew Svetlov: http://greentreesnakes.readthedocs.org/en/latest/index.html is excellent and comprehensive documentation for ast tree structures. It would be nice to incorporate that docs into stdlib documentation, but adding *see also* section is good enoigh as first step. ---------- assignee: docs@python components: Documentation keywords: easy messages: 176239 nosy: asvetlov, docs@python priority: normal severity: normal stage: needs patch status: open title: Add external link to ast docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________

7 11

[issue17006] Warn users about hashing secrets?
by Christian Heimes 04 Jan '16

04 Jan '16

New submission from Christian Heimes: Lot's of people still think that something like sha512(secret + message), sha1(password + salt) or even sha1(password) is secure. Except it isn't. Most crypto hash functions like md5, sha1, sha2 family (sha256, sha384, sha512) use a Merkle–Damgård construction [1]. The construction is vulnerable to several attack vectors like length extension attacks. Passwords needs special care, too. I propose we add a warning to the documentation of hashlib. It's not the right place to teach cryptographics but it's a good place to raise attention. The warning should explain that you shouldn't solely hash secrets or messages containing a secret. For messages a MAC algorithm like HMAC should be used. For passwords a key stretching and key derivation function like PBKDF2, bcrypt or scrypt is much more secure. [1] http://en.wikipedia.org/wiki/Merkle%E2%80%93Damg%C3%A5rd_construction ---------- assignee: docs@python components: Documentation messages: 180330 nosy: christian.heimes, docs@python priority: normal severity: normal status: open title: Warn users about hashing secrets? type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17006> _______________________________________

14 26

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

27 Dec '15

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 26 Nov '15

26 Nov '15

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 26 Nov '15

26 Nov '15

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