Mailman 3 March 2012 - docs

[issue9196] Improve docs for string interpolation "%s" re Unicode strings
by Craig McQueen May 31, 2020

May 31, 2020

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()". Here is what I have found (I think), and it could be worth improving the documentation of this somehow. Example 1: "%s" % test_object >From what I can tell, in this case: 1. test_object.__str__() is called. 2. If test_object.__str__() returns a string object, then that is substituted. 3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising. [Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.] Example 2: u"%s" % test_object In this case: 1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode. 2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode. Example 3: "%s %s" % (u'unicode', test_object) In this case: 1. The first substitution causes the output string to be Unicode. 2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising. ---------- assignee: docs@python components: Documentation messages: 109516 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Improve docs for string interpolation "%s" re Unicode strings versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9196> _______________________________________

5 10

[issue11425] Cleanup sample codes in tutorial.
by INADA Naoki May 14, 2020

May 14, 2020

New submission from INADA Naoki <songofacandy(a)gmail.com>: * Insert spaces around operators and after commas. * Split one liner blocks (ex. def foo(x, y): return x + y) to multi-line blocks. * Insert empty line after def block for scripts (not interactive mode). * Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/) * Use x ** 3 instead of x * x * x. Attached patch is for Python 2.6. I'll make same changes for Python 3.1 if this patch is accepted. ---------- assignee: docs@python components: Documentation files: cleanup_tutorial_codes.patch keywords: patch messages: 130225 nosy: docs@python, naoki priority: normal severity: normal status: open title: Cleanup sample codes in tutorial. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11425> _______________________________________

5 5

[issue8940] *HTTPServer need a summary page with API inheritance table
by anatoly techtonik April 27, 2020

April 27, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: The abundance of methods and hierarchy depth of various servers from "Internet Protocols and Support" section makes it extremely hard to navigate information. You need a strong OOP background to be able to use this doc effectively, as examples are not intuitive otherwise. Usually you need a decent IDE (such as Eclipse) to get a picture of class hierarchy and a table of all available methods with a mark where they were inherited from. Such table (at least Class Hierarchy view screenshot from Eclipse) should be available in reference for descendant classes. ---------- assignee: docs@python components: Documentation messages: 107321 nosy: docs@python, techtonik priority: normal severity: normal status: open title: *HTTPServer need a summary page with API inheritance table versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8940> _______________________________________

6 7

[issue14418] Document differences in SocketServer between Python 2.6 and 2.7
by Geoffrey Bache April 27, 2020

April 27, 2020

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: Here I'm referring to the section about RequestHandler objects under the SocketServer page. http://docs.python.org/release/2.7.2/library/socketserver.html#requesthandl… This appears to be the same in Python 2.6 and Python 2.7. But the objects don't behave the same, in two respects: 1) For finish() "If setup() or handle() raise an exception, this function will not be called." This is true in Python 2.6. It appears to no longer be true in Python 2.7, where finish() is called in a "finally" clause. 2) For handle(). "The default implementation does nothing". This is true up to a point, but using the default implementation has different effects. Specifically, if I try to read from a socket when the server has not written anything, I get an exception in Python 2.6 and an empty string in Python 2.7. Consider this code: ## server.py from SocketServer import TCPServer, StreamRequestHandler import sys, socket server = TCPServer((socket.gethostname(), 0), StreamRequestHandler) host, port = server.socket.getsockname() address = host + ":" + str(port) print "Started server at", address sys.stdout.flush() server.serve_forever() ## client.py import sys, socket servAddr = sys.argv[1] host, port = servAddr.split(":") serverAddress = (host, int(port)) sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect(serverAddress) sock.sendall("Some Message") sock.shutdown(1) response = sock.makefile().read() print "Got reply:", response sock.close() and compare the following: $ python2.7 server.py & Started server at 127.0.1.1:42759 $ python2.7 client.py 127.0.1.1:42759 Got reply: $ python2.6 server.py & Started server at 127.0.1.1:42758 $ python client.py 127.0.1.1:42758 Traceback (most recent call last): File "client.py", line 12, in <module> response = sock.makefile().read() File "/usr/lib/python2.7/socket.py", line 351, in read data = self._sock.recv(rbufsize) socket.error: [Errno 104] Connection reset by peer (doesn't matter which Python runs the client in the last case) I am unsure whether this is a bug in Python 2.6, or really what the reasoning behind the behaviour difference is, but I think this change in behaviour is worth a small note in the documentation (how it will behave if you try to read when nothing has been written) ---------- assignee: docs@python components: Documentation messages: 156869 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Document differences in SocketServer between Python 2.6 and 2.7 versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14418> _______________________________________

5 5

[issue13743] xml.dom.minidom.Document class is not documented
by Sandro Tosi April 12, 2020

April 12, 2020

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hello, following up http://mail.python.org/pipermail/docs/2012-January/007026.html I noticed the whole Document class (and relative methods) is not documented. Maybe it is a choice to not document it, or maybe it's just a missing doc, dunno, the's why I'm opening this :) ---------- assignee: docs@python components: Documentation messages: 150935 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: xml.dom.minidom.Document class is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13743> _______________________________________

6 9

[issue13077] Unclear behavior of daemon threads on main thread exit
by etuardu March 9, 2020

March 9, 2020

New submission from etuardu <edonan(a)gmail.com>: The definition of daemon thread in the current documentation reads: «A thread can be flagged as a "daemon thread". The significance of this flag is that the entire Python program exits when only daemon threads are left. [...]» (http://docs.python.org/library/threading.html#thread-objects) I think it's not very clear from this that daemon threads themselves terminate when the program (main thread plus other non-daemon threads) terminates. I think this have to be said more explicitly. I'd propose a change with something like: «A thread can be flagged as a "daemon thread", which means it will get shut down when the overall program terminates. The entire Python program exits when only daemon threads are left.» ---------- assignee: docs@python components: Documentation messages: 144691 nosy: docs@python, etuardu priority: normal severity: normal status: open title: Unclear behavior of daemon threads on main thread exit type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13077> _______________________________________

5 7

[issue8824] Improve documentation of exec
by Terry J. Reedy Feb. 28, 2020

Feb. 28, 2020

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread 'variable name resolution in exec is incorrect' (which is not a correct claim). I believe there is consensus that the doc for exec needs improving. My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry) "In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary, which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object." have these two sentences added: "If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope." ---------- assignee: docs@python components: Documentation messages: 106552 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Improve documentation of exec versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8824> _______________________________________

6 19

[issue9056] Adding additional level of bookmarks and section numbers in python pdf documents.
by pengyu.ut Feb. 18, 2020

Feb. 18, 2020

New submission from pengyu.ut <pengyu.ut(a)gmail.com>: Current pdf version of python documents don't have bookmarks for sussubsection. For example, there is no bookmark for the following section in python_2.6.5_reference.pdf. Also the bookmarks don't have section numbers in them. I suggest to include the section numbers. Could these features be added in future release of python document. 3.4.1 Basic customization ---------- assignee: docs@python components: Documentation messages: 108334 nosy: docs@python, pengyu.ut priority: normal severity: normal status: open title: Adding additional level of bookmarks and section numbers in python pdf documents. versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9056> _______________________________________

7 9

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky Feb. 14, 2020

Feb. 14, 2020

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC. or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. I believe geographical references in the python documentation are irrelevant. What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid. I suggest the following wording for time.timezone description: time.timezone: The number of seconds one must add to the local time to arrive at UTC. Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time." ---------- assignee: docs@python components: Documentation keywords: easy messages: 110774 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Don't use east/west of UTC in date/time documentation type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

15 30

[issue13826] Having a shlex example in the subprocess.Popen docs is confusing
by Julian Berman Feb. 10, 2020

Feb. 10, 2020

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere. ---------- assignee: docs@python components: Documentation messages: 151624 nosy: Julian, docs@python priority: normal severity: normal status: open title: Having a shlex example in the subprocess.Popen docs is confusing type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13826> _______________________________________

9 14