Mailman 3 December 2014 - docs

Re: [docs] argparse required arguments displayed under "optional arguments" (issue 9694)
by berker.peksag＠gmail.com 16 Dec '14

16 Dec '14

https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst File Doc/library/argparse.rst (right): https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst#new… Doc/library/argparse.rst:1711: "positional arguments" and "options" when displaying help On 2014/12/16 21:50:28, vadmium wrote: > Maybe I should also add a “Changed in version 3.5” notice for this +1. That would be good. https://bugs.python.org/review/9694/

1 0

[issue17876] Doc issue with threading.Event
by Xavier Ordoquy 16 Dec '14

16 Dec '14

New submission from Xavier Ordoquy: The documentation isn't correct for the threading.Event class under python 3.2. In the threading doc page (http://docs.python.org/3.2/library/threading.html), Event is said to be at the same time a function and a class. This is misleading and lead to a regression for celery under python 3.2 (https://github.com/celery/celery/pull/1333). Could the doc be updated under python 3.2 so that threading.Event leads to the function and threading._Event leads to the class ? Regards, Xavier. ---------- assignee: docs@python components: Documentation messages: 188127 nosy: docs@python, xordoquy priority: normal severity: normal status: open title: Doc issue with threading.Event type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17876> _______________________________________

4 5

[issue21071] struct.Struct.format is bytes, but should be str
by Martin Panter 16 Dec '14

16 Dec '14

Martin Panter added the comment: It seems to me that the simplest fix is to document: 1. Struct.format attribute is a byte string 2. The input format strings for struct.pack(), Struct class, etc, are also allowed to be byte strings, for consistency (Issue 16349) Here is a patch that does that, and adds some simple test cases. ---------- keywords: +patch Added file: http://bugs.python.org/file37474/format-bytes.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21071> _______________________________________

1 0

argparse required arguments displayed under "optional arguments" (issue 9694)
by vadmium+py＠gmail.com 16 Dec '14

16 Dec '14

https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst File Doc/library/argparse.rst (right): https://bugs.python.org/review/9694/diff/13424/Doc/library/argparse.rst#new… Doc/library/argparse.rst:1711: "positional arguments" and "options" when displaying help Maybe I should also add a “Changed in version 3.5” notice for this https://bugs.python.org/review/9694/

1 0

[issue9694] argparse required arguments displayed under "optional arguments"
by Martin Panter 16 Dec '14

16 Dec '14

Martin Panter added the comment: Here is much larger patch in the spirit of Ryan’s, that fixes the documentation, adjusts the tests, and some of the internal comments and variable names in the source code as well. However if some changes are too controversial, I am happy to simplify it to (say) Ryan’s patch plus the minimum test fixes. ---------- versions: +Python 3.5 Added file: http://bugs.python.org/file37461/option-internal.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9694> _______________________________________

1 0

filecmp.cmp "shallow" documentation
by Jeff Kaufman 15 Dec '14

15 Dec '14

If you have two files with identical size, mode, and mtime, filecmp.cmp will return them as equal with its "shallow" option, which is on by default. This is documented in 2.x as: Unless shallow is given and is false, files with identical os.stat() signatures are taken to be equal. and in 3.x as: If shallow is true, files with identical os.stat() signatures are taken to be equal. Otherwise, the contents of the files are compared. This doesn't explain what is included in the signature. On initial reading, I had thought it would do something like "os.stat(a) == os.stat(b)", but it instead pulls out just the size, mode, and mtime for comparison. Could we document this? Perhaps: - ... files with identical os.stat() signatures are ... + ... files with identical size, mode, and mtime given by os.stat() are ..." (This bit me with https://github.com/jeffkaufman/icdiff/issues/37 where I had thought inode number would be included in the stat signature.)

1 0

[issue22875] asyncio: call_soon() documentation unclear on timing
by Corbin Simpson 15 Dec '14

15 Dec '14

New submission from Corbin Simpson: Hi there! While assisting somebody on #python (where manners go to die), I was consulting asyncio's documentation. Given my unfamiliarity with asyncio, I was surprised to read BaseEventLoop.call_soon()'s documented behavior: "Arrange for a callback to be called as soon as possible." [1] The question in mind is whether call_soon() waits for control to return to the event loop before calling the first callback in the queue. After all, given the documented behavior, it would not be unreasonable for call_soon() to always call callbacks immediately if no other callbacks were enqueued. I can imagine scenarios where a previous queued callback from e.g. call_soon_threadsafe() creates a callback that causes queueing behavior, but otherwise I would expect "as soon as possible" to mean "immediately". It's true that in other event loops, this kind of callback registration waits for control to return to the event loop before running callbacks. However, many event loops that I've worked with indicate that call_later() is the correct API for adding callbacks that respect the event loop. In fact, call_later(0, callback, args) looks quite a bit like the familiar Twisted callLater(0, callback, args) pattern! Additionally, there is no indication as to whether call_later() and call_soon() use the same queue. I'd like clarification on these points in the Python 3 documentation, please. I'd like to know whether call_soon() can be immediate, and whether call_soon() preempts or interleaves with call_later(). (Yes, I know that Twisted's documentation is missing this too [2] [3]. I'll get to that soon enough.) Thanks! ~ C. [1]: https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventL… [2]: http://twistedmatrix.com/documents/current/core/howto/time.html [3]: http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.… ---------- assignee: docs@python components: Documentation, asyncio messages: 231180 nosy: Corbin.Simpson, docs@python, gvanrossum, haypo, yselivanov priority: normal severity: normal status: open title: asyncio: call_soon() documentation unclear on timing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22875> _______________________________________

5 7

Re: [docs] str.translate documentation incomplete (issue 21279)
by JohnJPosner＠verizon.net 14 Dec '14

14 Dec '14

Using this mechanism for the first time. Please let me know if I'm using it incorrectly. http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst File Doc/library/stdtypes.rst (right): http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst#new… Doc/library/stdtypes.rst:1912: Return a copy of the string where all characters have been mapped through the I suggest a revised paragraph, combining this one with the comments made by Terry Reedy. IMO, it's important to point out that a LookupError produced by the translation table does not cause the translate() method to fail. Rather, translate() catches the exception and sends the character, unchanged, to the return string. Here's my suggested paragraph: Return a copy of the string *str* in which each character has been mapped through the given translation *table*. The translation table must be a subscriptable object, for instance a list or dictionary; when subscripted (indexed) by a Unicode ordinal (an integer in range(1048576)), the table object can yield a Unicode ordinal, a string, or None -- or else can raise a LookupError. A LookupError (typically, an instance of subclass IndexError or KeyError) is caught by translate; the character is sent, unchanged, to the return string. A character mapped to None is deleted from the return string. And here's a possible alternative for the first sentence: Map each character of the string *str* through the given translation *table*, and return the resulting string. http://bugs.python.org/review/21279/

1 0

[issue23011] Duplicate Paragraph in documentation for json module
by berndca 13 Dec '14

13 Dec '14

New submission from berndca: There is a duplication of the first section of 18.2.2 (JSON) Encoders and Decoders of the python 2.7.9RC1 doc as well of the corresponding paragraph in 19.2.2 of the Python 3 docs. ---------- assignee: docs@python components: Documentation messages: 232303 nosy: berndca, docs@python priority: normal severity: normal status: open title: Duplicate Paragraph in documentation for json module type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23011> _______________________________________

3 3

[issue23017] string.printable.isprintable() returns False
by Akira Li 13 Dec '14

13 Dec '14

Akira Li added the comment: C standard defines locale-specific *printing characters* that are [ -~] in "C" locale for implementations that use 7-bit US ASCII character set i.e., SP (space, 0x20) is a printing character in C (isprint() returns nonzero). There is isgraph() function that returns zero for the space but otherwise is equivalent to isprint(). POSIX definition is aligned with the ISO C standard. I don't know what RFC 5822 has to do with this issue but the rfc contradicts itself e.g., in one place it has: "printable US-ASCII characters except SP" that imlies that SP *is* printable but in other places it considers isprint==isgraph. The authors probably meant characters for which isgraph() is nonzero when they use "printable US-ASCII" (that is incorrect according to C standard). Tests from issue9770 show the relation between C character classes and string constants [1]: set(string.printable) == set(C['graph']) + set(C['space']) where C['space'] is '\t\n\v\f\r ' (the standard C whitespace). It is a documented behavior [2]: This is a combination of digits, ascii_letters, punctuation, and whitespace where *whitespace* is C['space']. In Python 2, *printable* is locale-dependent and it coincides with the corresponding Python 3 definition in "C" locale with ASCII charset. Unlike other string constants, *printable* differs from C['print'] on both Python 2 and 3 because it includes whitespace characters other than space. str.isprintable [3] obeys C['print'] (in ASCII range) and considers SP to be printable. --- It might be too late to change string.printable to correspond to C isprint() (for ASCII characters). I've uploaded a documentation patch that mentions that string.printable and str.isprintable differ. [1] http://bugs.python.org/review/9770/diff/12212/Lib/test/test_curses_ascii.py [2] https://hg.python.org/cpython/file/3.4/Doc/library/string.rst#l62 [3] https://docs.python.org/3.4/library/stdtypes.html#str.isprintable ---------- nosy: +akira Added file: http://bugs.python.org/file37441/docs-string.printable.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23017> _______________________________________

1 0