Mailman 3 November 2014 - docs

[issue21092] json serializer implicitly stringifies non-string keys
by Chris Rebert 11 Jan '15

11 Jan '15

New submission from Chris Rebert: Python 3.3.4 (default, Feb 21 2014, 18:00:34) [GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.2.79)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> from json import dumps >>> dumps({True: True, False: False, None: None, 42: 42}) '{"false": false, "true": true, "42": 42, "null": null}' >>> This implicit stringification of non-string dictionary keys does not currently appear to be documented. ---------- assignee: docs@python components: Documentation messages: 215105 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: json serializer implicitly stringifies non-string keys versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21092> _______________________________________

5 4

[issue20487] Odd words in unittest.mock document.
by INADA Naoki 07 Jan '15

07 Jan '15

New submission from INADA Naoki: http://docs.python.org/3.3/library/unittest.mock.html#magic-mock > The two equality method, __eq__ and __ne__, are special. They do the default equality comparison on identity, using a side effect, unless you change their return value to return something else: What "using a side effect" means? ---------- assignee: docs@python components: Documentation messages: 209993 nosy: docs@python, michael.foord, naoki priority: normal severity: normal status: open title: Odd words in unittest.mock document. versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20487> _______________________________________

6 8

[issue19548] 'codecs' module docs improvements
by Jan Kaliszewski 07 Jan '15

07 Jan '15

New submission from Jan Kaliszewski: When learning about the 'codecs' module I encountered several places in the docs of the module that, I believe, could be improved to be clearer and easier for codecs-begginers: 1. Ad `codecs.encode` and `codecs.decode` descriptions: I believe it would be worth to mention that, unlike str.encode()/bytes.decode(), these functions (and all their counterparts in the classes the module contains) support not only "traditional str/bytes encodings", but also bytes-to-bytes as well as str-to-str encodings. 2. Ad 'codecs.register': in two places there is such a text: `These have to be factory functions providing the following interface: factory([...] errors='strict')` -- `errors='strict'` may be confusing (at the first sight it may suggest that the only valid value is 'strict'; maybe `factory(errors=<error handler label>)` with an appropriate description below would be better?). 3. Ad `codecs.open`: I believe there should be a reference to the built-in open() as an alternative that is better is most cases. 4. Ad `codecs.BOM*`: `These constants define various encodings of the Unicode byte order mark (BOM).` -- the world `encodings` seems to be confusing here; maybe `These constants define various byte sequences being Unicode byte order marks (BOMs) for several encodings. They are used...` would be better? 5. Ad `7.2.1. Codec Base Classes` + `codecs.IncrementalEncoder`/`codecs/IncrementalDecoder`: * `Each codec has to define four interfaces to make it usable as codec in Python: stateless encoder, stateless decoder, stream reader and stream writer` -- only four? Not six? What about incremental encoder/decoder??? * Comparing the fragments (and tables) about error halding methods (Codecs Base Classes, IncrementalEncoder, IncrementalDecoder) with similar fragment in the `codecs.register` description and with the `codecs.register_error` description I was confused: is it the matter of a particular codec implementation or of a registered error handler to implement a particular way of error handling? I believe it would be worth to describe clearly relations between these elements of the API. Also more detailed description of differences beetween error handling for encoding and decoding, and translation would be a good thing. 6. Ad `7.2.1.6. StreamReaderWriter Objects` and `7.2.1.7. StreamRecoder Objects`: It would be worth to say explicitly that, contrary to previously described abstract classes (IncrementalEncoder/Decoder, StreamReader/Writer), these classes are *concrete* ones (if I understand it correctly). 7. Ad `7.2.4. Python Specific Encodings`: * `raw_unicode_encoding` -- see: ticket #19539. * `unicode_encoding` -- `Produce a string that is suitable as Unicode literal in Python source code` but it is *not* a string; it's a *bytes* object (which could be used in source code using an `ascii`-compatibile encoding). * `bytes-to-bytes` and `str-to-str` encodings -- maybe it would be nice to mention that these encodings cannot be used with str.encode()/bytes.decode() methods (and to mention again they *can* be used with the functions/method provided by the `codecs` module). ---------- assignee: docs@python components: Documentation messages: 202593 nosy: docs@python, zuo priority: normal severity: normal status: open title: 'codecs' module docs improvements 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/issue19548> _______________________________________

12 30

[issue20606] Operator Documentation Example doesn't work
by silentbat 04 Jan '15

04 Jan '15

New submission from silentbat: In the Docs for Python3.3 http://docs.python.org/3.3/library/operator.html#operator.__setitem__ the following example doesn't work. ---------- assignee: docs@python components: Documentation messages: 211079 nosy: docs@python, silent.bat priority: normal severity: normal status: open title: Operator Documentation Example doesn't work type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20606> _______________________________________

6 7

[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

[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

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner 12 Dec '14

12 Dec '14

New submission from John Posner <jjposner(a)optimum.net>: The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__. The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine. ---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9536> _______________________________________

7 11

[issue22918] Doc for __iter__ makes inexact comment about dict.__iter__
by Éric Araujo 10 Dec '14

10 Dec '14

New submission from Éric Araujo: https://docs.python.org/3/reference/datamodel#object.__iter__ > This method should return a new iterator object that can iterate over all the objects > in the container. For mappings, it should iterate over the keys of the container, and > should also be made available as the method keys(). In 3.x, d.__iter__() is not equivalent to d.keys() but to iter(d.keys()). ---------- assignee: docs@python components: Documentation keywords: easy messages: 231529 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Doc for __iter__ makes inexact comment about dict.__iter__ versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22918> _______________________________________

6 9

[issue22581] Other mentions of the buffer protocol
by Serhiy Storchaka 05 Dec '14

05 Dec '14

New submission from Serhiy Storchaka: In addition to issue16518. There are other non-fixed messages (may be introduced after 3.3): >>> b''.join(['']) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: sequence item 0: expected bytes, bytearray, or an object with the buffer interface, str found >>> str(42, 'utf8') Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: coercing to str: need bytes, bytearray or buffer-like object, int found >>> import array; array.array('B').frombytes(array.array('I')) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: string/buffer of bytes required. >>> import socket; print(socket.socket.sendmsg.__doc__) sendmsg(buffers[, ancdata[, flags[, address]]]) -> count Send normal and ancillary data to the socket, gathering the non-ancillary data from a series of buffers and concatenating it into a single message. The buffers argument specifies the non-ancillary data as an iterable of buffer-compatible objects (e.g. bytes objects). The ancdata argument specifies the ancillary data (control messages) as an iterable of zero or more tuples (cmsg_level, cmsg_type, cmsg_data), where cmsg_level and cmsg_type are integers specifying the protocol level and protocol-specific type respectively, and cmsg_data is a buffer-compatible object holding the associated data. The flags argument defaults to 0 and has the same meaning as for send(). If address is supplied and not None, it sets a destination address for the message. The return value is the number of bytes of non-ancillary data sent. And there are several mentions of "buffer-like" or "buffer-compatible" in the documentation. ---------- assignee: docs@python components: Documentation keywords: easy messages: 228799 nosy: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, flox, georg.brandl, pitrou, python-dev, r.david.murray, rhettinger, serhiy.storchaka, skrah, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Other mentions of the buffer protocol _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22581> _______________________________________

5 14

[issue22394] Update documentation building to use venv and pip
by Brett Cannon 05 Dec '14

05 Dec '14

New submission from Brett Cannon: Now that we have ensurepip, is there any reason to not have the Doc/ Makefile create a venv for building the docs instead of requiring people to install sphinx into either their global Python interpreter or some venv outside of their checkout? Basically it would be like going back to the old Makefile of checking out the code but instead do a better isolation job and let pip manage fetching everything, updating the projects, etc. ---------- assignee: docs@python components: Documentation messages: 226821 nosy: brett.cannon, docs@python priority: low severity: normal stage: needs patch status: open title: Update documentation building to use venv and pip type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22394> _______________________________________

4 7