docs November 2012

docs@python.org

41 participants
508 discussions

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return

by Baruch Sterin

New submission from Baruch Sterin <python(a)bsterin.com>: In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.'). The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have. The list has been generated automatically, so it might contain some errors. Doc/c-api/arg.rst: Py_VaBuildValue Doc/c-api/buffer.rst: PyMemoryView_FromBuffer Doc/c-api/buffer.rst: PyMemoryView_FromObject Doc/c-api/buffer.rst: PyMemoryView_GetContiguous Doc/c-api/bytearray.rst: PyByteArray_Concat Doc/c-api/bytearray.rst: PyByteArray_FromObject Doc/c-api/bytearray.rst: PyByteArray_FromStringAndSize Doc/c-api/code.rst: PyCode_New Doc/c-api/codec.rst: PyCodec_BackslashReplaceErrors Doc/c-api/codec.rst: PyCodec_Decode Doc/c-api/codec.rst: PyCodec_Decoder Doc/c-api/codec.rst: PyCodec_Encode Doc/c-api/codec.rst: PyCodec_Encoder Doc/c-api/codec.rst: PyCodec_IgnoreErrors Doc/c-api/codec.rst: PyCodec_IncrementalDecoder Doc/c-api/codec.rst: PyCodec_IncrementalEncoder Doc/c-api/codec.rst: PyCodec_LookupError Doc/c-api/codec.rst: PyCodec_ReplaceErrors Doc/c-api/codec.rst: PyCodec_StreamReader Doc/c-api/codec.rst: PyCodec_StreamWriter Doc/c-api/codec.rst: PyCodec_StrictErrors Doc/c-api/codec.rst: PyCodec_XMLCharRefReplaceErrors Doc/c-api/exceptions.rst: PyUnicodeDecodeError_Create Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetEncoding Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetObject Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetReason Doc/c-api/exceptions.rst: PyUnicodeEncodeError_Create Doc/c-api/exceptions.rst: PyUnicodeTranslateError_Create Doc/c-api/float.rst: PyFloat_GetInfo Doc/c-api/import.rst: PyImport_GetImporter Doc/c-api/import.rst: PyImport_ImportModuleNoBlock Doc/c-api/import.rst: _PyImport_FindExtension Doc/c-api/import.rst: _PyImport_FixupExtension Doc/c-api/init.rst: PyEval_GetCallStats Doc/c-api/int.rst: PyInt_FromSize_t Doc/c-api/long.rst: PyLong_FromSize_t Doc/c-api/long.rst: PyLong_FromSsize_t Doc/c-api/number.rst: PyNumber_Index Doc/c-api/number.rst: PyNumber_ToBase Doc/c-api/object.rst: PyObject_Bytes Doc/c-api/object.rst: PyObject_GenericGetAttr Doc/c-api/unicode.rst: PyUnicode_AsUTF32String Doc/c-api/unicode.rst: PyUnicode_DecodeMBCSStateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32Stateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7Stateful Doc/c-api/unicode.rst: PyUnicode_EncodeUTF32 Doc/c-api/unicode.rst: PyUnicode_EncodeUTF7 Doc/c-api/veryhigh.rst: PyEval_EvalCodeEx Doc/c-api/veryhigh.rst: PyEval_EvalFrame Doc/c-api/veryhigh.rst: PyEval_EvalFrameEx ---------- assignee: docs@python components: Documentation messages: 154877 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Documentation for some C APIs is missing clear specification of the type of reference they return type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14189> _______________________________________

1 month

[issue13649] termios.ICANON is not documented

by anatoly techtonik

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/termios.html is missing documentation for ICANON flag used to put terminal to "raw" mode. It is also worth to place `termios` raw/canonical mode equivalent on `tty` pages, so that people porting C code to Python could understand the hidden magic. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 150098 nosy: docs@python, techtonik priority: normal severity: normal status: open title: termios.ICANON is not documented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13649> _______________________________________

2 months, 1 week

[issue9196] Improve docs for string interpolation "%s" re Unicode strings

by Craig McQueen

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> _______________________________________

2 months, 1 week

[issue15952] format(value) and value.__format__() behave differently with unicode format

by Chris Jerdonek

New submission from Chris Jerdonek: format(value) and value.__format__() behave differently even though the documentation says otherwise: "Note: format(value, format_spec) merely calls value.__format__(format_spec)." (from http://docs.python.org/library/functions.html?#format ) The difference happens when the format string is unicode. For example: >>> format(10, u'n') u'10' >>> (10).__format__(u'n') # parentheses needed to prevent SyntaxError '10' So either the documentation should be changed, or the behavior should be changed to match. Related to this: neither the "Format Specification Mini-Language" documentation nor the string.Formatter docs seem to say anything about the effect that a unicode format string should have on the return value (in particular, should it cause the return value to be unicode or not): http://docs.python.org/library/string.html#formatspec http://docs.python.org/library/string.html#string-formatting See also issue 15276 (int formatting), issue 15951 (empty format string), and issue 7300 (unicode arguments). ---------- assignee: docs@python components: Documentation messages: 170575 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: format(value) and value.__format__() behave differently with unicode format type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15952> _______________________________________

2 months, 1 week

[issue11425] Cleanup sample codes in tutorial.

by INADA Naoki

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> _______________________________________

2 months, 3 weeks

[issue8940] *HTTPServer need a summary page with API inheritance table

by anatoly techtonik

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> _______________________________________

3 months, 1 week

[issue14418] Document differences in SocketServer between Python 2.6 and 2.7

by Geoffrey Bache

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> _______________________________________

3 months, 1 week

[issue14759] Berkeley DB License conditions are onerous (and poorly documented)

by Jeff Laing

New submission from Jeff Laing <jefflaing(a)gmail.com>: As part of an audit of license compliance, I was looking at the terms in the LICENSE.txt that describe the Berkeley DB product. I had thought this would be under the standard Berkeley license, but Oracle have added their own zinger. * 3. Redistributions in any form must be accompanied by information on * how to obtain complete source code for the DB software and any * accompanying software that uses the DB software. The source code * must either be included in the distribution or be available for no * more than the cost of distribution plus a nominal fee, and must be * freely redistributable under reasonable conditions. So, my application, which embeds Python (rather than running it as python.exe) and includes the standard runtime library, must distribute my source code. This page: http://mail.python.org/pipermail/python-dev/2008-September/082316.html suggests that this is not the case for regular Python, but it makes no statement about "embedding". Sadly the Oracle page it links to suggesting this is not an issue, does not exist. The general "License" page on the Python websites makes no reference whatsoever to Berkeley DB license obligations. I note that there are other modules mentioned on the Licenses webpage that are not in the LICENSES.txt file, and vice versa. I have no idea whether this is deliberate, or an oversight. ---------- assignee: docs@python components: Documentation messages: 160238 nosy: Jeff.Laing, docs@python priority: normal severity: normal status: open title: Berkeley DB License conditions are onerous (and poorly documented) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14759> _______________________________________

3 months, 1 week

[issue13743] xml.dom.minidom.Document class is not documented

by Sandro Tosi

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> _______________________________________

3 months, 3 weeks

[issue15140] PEP 384 inconsistent with implementation

by Antoine Pitrou

New submission from Antoine Pitrou <pitrou(a)free.fr>: In PEP 384, the PyType_Spec struct has a "const char *doc" that is not present in the implementation (Include/object.h). ---------- assignee: docs@python components: Documentation messages: 163449 nosy: docs@python, loewis, pitrou priority: normal severity: normal stage: needs patch status: open title: PEP 384 inconsistent with implementation type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15140> _______________________________________

4 months, 1 week

Jump to page:

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs November 2012