Mailman 3 June 2015 - docs

[issue16554] The description of the argument of MAKE_FUNCTION and MAKE_CLOSURE is incorrect
by Daniel Urban Aug. 13, 2015

Aug. 13, 2015

New submission from Daniel Urban: The description of the argument of the MAKE_FUNCTION and MAKE_CLOSURE opcodes in the documentation of the dis module is incorrect. Patch attached. ---------- assignee: docs@python components: Documentation files: make_function_closure.patch keywords: needs review, patch messages: 176390 nosy: daniel.urban, docs@python priority: normal severity: normal stage: patch review status: open title: The description of the argument of MAKE_FUNCTION and MAKE_CLOSURE is … [View More]

4 4

[issue23756] Tighten definition of bytes-like objects
by Martin Panter Aug. 8, 2015

Aug. 8, 2015

New submission from Martin Panter: There are moves at documenting and implementing support for “bytes-like” objects in more APIs, such as the “io” module (Issue 20699), http.client (Issue 23740). The glossary definition is currently “An object that supports the Buffer Protocol, like bytes, bytearray or memoryview.” This was originally added for Issue 16518. However after reading Issue 23688, I realized that it should probably not mean absolutely _any_ object supporting the buffer protocol. For … [View More]instance: >>> reverse_view = memoryview(b"123")[::-1] >>> stdout.buffer.write(reverse_view) Traceback (most recent call last): File "<stdin>", line 1, in <module> BufferError: memoryview: underlying buffer is not C-contiguous I think the definition should at least be tightened to only objects with a contiguous buffer, and “contiguous” should be defined (probably in the linked C API page or the memoryview.contiguous flag definition, not the glossary). So far, my understanding is these are contiguous: * A zero-dimensional object, such as a ctypes object * An multi-dimensional array with items stored contiguously in order of increasing indexes. I.e. a_2,2 is stored somewhere after both a_1,2 and a_2,1, and all the strides are positive. and these are not contiguous: * memoryview(contiguous)[::2], because there are memory gaps between the items * memoryview(contiguous)[::-1], despite there being no gaps nor overlapping items * Views that set the “suboffsets” field (i.e. include pointers to further memory) * Views where different array items overlap each other (e.g. 0 in view.strides) Perhaps the bytes-like definition should tightened further, to match the above error message, to only “C-contiguous” buffers. I understand that C-contiguous means the strides tuple has to be in non-strict decreasing order, e.g. for 2 × 1 × 3 arrays, strides == (3, 3, 1) is C-contiguous, but strides == (1, 3, 3) is not. This also needs documenting. I’m not so sure about these, but the definition could be tightened even further: * Require memoryview(x).cast("B") to be supported. Otherwise, native Python code would have to use workarounds like struct.pack_into() to write to the “bytes-like” object. See Issue 15944. * Require len(view) == view.nbytes. This would help in some cases avoid the bug that I have seen of code naively calling len(data), but the downside is ctypes objects would no longer be considered bytes-like objects. ---------- assignee: docs@python components: Documentation messages: 239097 nosy: docs@python, vadmium priority: normal severity: normal status: open title: Tighten definition of bytes-like objects _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23756> _______________________________________ [View Less]

7 25

[issue24531] please document that no code preceding encoding declaration is allowed
by Jakub Wilk Aug. 6, 2015

Aug. 6, 2015

New submission from Jakub Wilk: If the encoding is declared on the second line, the first line must not contain anything except comments. However, this fact is not documented. The Python Language reference says only that "the encoding declaration must appear on a line of its own"; and PEP 263 says only that "there must not be any Python statement on the line that contains the encoding declaration". For example, Python ignores this encoding declaration: spam = True # encoding=ISO-8859-2 … [View More]

5 5

[issue21279] str.translate documentation incomplete
by bob gailer Aug. 6, 2015

Aug. 6, 2015

New submission from bob gailer: Documentation for str.translate only mentions a dictionary for the translation table. Actually any iterable can be used, as long as its elements are integer, None or str. Recommend wording: str.translate(translation_table) Return a copy of the s where all characters have been "mapped" through the translation_table - which must be either a dictionary mapping Unicode ordinals (integers) to Unicode ordinals, strings or None, or an iterable. In this case the ord()… [View More]

11 26

[issue24129] Incorrect (misleading) statement in the execution model documentation
by levkivskyi Aug. 5, 2015

Aug. 5, 2015

New submission from levkivskyi: The documentation on execution model https://docs.python.org/3/reference/executionmodel.html contains the statement """ A class definition is an executable statement that may use and define names. These references follow the normal rules for name resolution. The namespace of the class definition becomes the attribute dictionary of the class. Names defined at the class scope are not visible in methods. """ However, the following code (taken from http://… [View More]

9 22

[issue20769] Reload() description is unclear
by Roy Smith Aug. 4, 2015

Aug. 4, 2015

New submission from Roy Smith: http://docs.python.org/2/library/functions.html#reload says: It is legal though generally not very useful to reload built-in or dynamically loaded modules, except for sys, __main__ and __builtin__. It is unclear what the "except for ..." part is referring to. Is it not legal to reload those modules? Or is it not very useful to reload them? ---------- assignee: docs@python components: Documentation messages: 212187 nosy: docs@python, roysmith priority: normal … [View More]

7 13

[issue24021] document urllib.urlretrieve
by Berker Peksag Aug. 4, 2015

Aug. 4, 2015

New submission from Berker Peksag: urllib.urlretrieve is already documented at https://docs.python.org/2.7/library/urllib.html#urllib.urlretrieve Can you please give us more information about your problem with the urllib.urlretrieve documentation? ---------- nosy: +berker.peksag _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24021> _______________________________________

7 7

[issue16508] include the "object" type in the lists of documented types
by Chris Jerdonek July 30, 2015

July 30, 2015

New submission from Chris Jerdonek: This issue is to add the "object" type to the list of types documented in the language reference's standard type hierarchy and the library reference's list of built-in types: http://docs.python.org/dev/reference/datamodel.html#the-standard-type-hiera… http://docs.python.org/dev/library/stdtypes.html#other-built-in-types The constructor is documented here: http://docs.python.org/dev/library/functions.html#object In the documentation, it might also be … [View More]

8 10

[issue24109] Documentation for difflib uses optparse
by Keith Gray July 29, 2015

July 29, 2015

New submission from Keith Gray: The documentation for optparse states it has been deprecated in favor of argparse since 2.7. However, the library documentation for difflib still uses optparse in the example. https://docs.python.org/2/library/difflib.html#a-command-line-interface-to-… https://docs.python.org/3.5/library/difflib.html#a-command-line-interface-t… I am willing to update the documentation if there is agreement that it is needed. ---------- assignee: docs@python components: … [View More]

4 7