Mailman 3 December 2014 - docs

[issue23100] multiprocessing doc organization impedes understanding
by Davin Potts 11 Jan '15

11 Jan '15

New submission from Davin Potts: The organization and multiple sections of the multiprocessing module's documentation do not adhere to the Python Dev Guidelines for economy of expression, affirmative tone, and/or code examples. Problem description: The raw material and information in the multiprocessing module docs are good to excellent and very information rich -- the presentation of that information suffers primarily from its organization. (1) Too much information is presented in the same or neighboring subsections where the economy of expression guidelines would advocate for a different approach. Specifically, section 17.2.2 "Reference" co-mingles discourses on usage topics with a description of the available objects and apis. Section 17.2.1 "Introduction" does something similar and though some of this can be helpful in an intro section, it takes discourse a bit far at times, arguably losing its focus which is to clearly introduce the reader to the module and efficiently set them on a healthy path to understanding topics and establish sufficient comfort to begin working with the module. Economy of expression would have us maintain focus in an Introduction or Reference section and re-organize such helpful discourses into supporting but distinct sections. (2) Affirmative tone is not consistently used throughout the docs. Multiple of the items under section 17.2.3 "Programming guidelines" leverage negative examples to motivate what should be done instead -- each of these can be rewritten in the way advocated in the Python Dev Guidelines for affirmative tone. (3) Per the Python Dev Guidelines for code examples, examples should accelerate understanding versus alternative prose. Code snippets showcasing internal behavior to the module, such as the "Beware of replacing sys.stdin" subsection inside 17.2.3.1 "All start methods", should arguably have their example code blocks replaced with prose. Section 17.2.4 "Examples" provides examples showcasing many facets all in the same example code block yet little to no supporting or motivating explanation is offered for each (more could be offered inline as well as outside as prose). Suggested changes: * Re-organize the single multiprocessing module doc into multiple in the style of the logging module. Specifically, tutorials should be created to house the "bunny trail" discourses from the Introduction/Reference sections and a cookbook should be created to house the material from the Examples section. * By de-bunny-trailing the Introduction/Reference sections, a more focused set of sections in the style of the threading module should result. * Limited modifications to code examples are advocated only so far as they restore the affirmative tone as needed. * New examples are not advocated as part of this issue; they are out-of-scope. This issue is intended to add to the path started/advocated by Issue 22952. It does not supplant but rather expands upon that issue. ---------- assignee: docs@python components: Documentation messages: 233030 nosy: davin, docs@python, rhettinger priority: normal severity: normal status: open title: multiprocessing doc organization impedes understanding type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23100> _______________________________________

3 3

[issue22952] multiprocessing doc introduction not in affirmative tone
by Davin Potts 11 Jan '15

11 Jan '15

New submission from Davin Potts: The introduction section of the multiprocessing module's documentation does not adhere to the python dev guidelines for keeping things in the affirmative tone. Problem description: Specifically, the intro section contains a warning block that, while conveying something important, both 1) potentially creates worry/concern in the mind of the reader new to this module, and 2) ideally belongs somewhere more relevant/appropriate than the intro section. Also, the intro section contains an example code block that does not attempt to provide a simple example to advance understanding and boost the reader's confidence through trying this example -- instead it demonstrates what not to do and the consequences of doing so in an attempt to drive home one key point with the reader. Suggested changes: * The warning text block can be moved to a section discussing synchronization without losing the important information being shared or sharing it too late to be useful. * To make the key point to the reader in the intro about the availability/importability of functions, etc. to child processes, the affirmative tone can be used in describing the good pattern/practice being employed in a usable/valid/working example. Further comment: Similar issues could be raised with other parts of the multiprocessing docs but this issue is concerned only with the intro section. ---------- assignee: docs@python components: Documentation messages: 231731 nosy: davin, docs@python priority: normal severity: normal status: open title: multiprocessing doc introduction not in affirmative tone type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________

5 10

[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 06 Jan '15

06 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

[issue18518] return-ing within code timed with timeit.timeit causes wrong return value of timeit.timeit
by Serhiy Storchaka 31 Dec '14

31 Dec '14

Serhiy Storchaka added the comment: May be add a guard against statements which can confuse timeit? These are not only "return", but "yield", and "break" and "continue" outside of a loop. Proposed patch checks that testing code can be compiled outside of a function. ---------- assignee: docs@python -> components: +Library (Lib) -Documentation nosy: +serhiy.storchaka stage: -> patch review versions: +Python 3.5 -Python 3.3 Added file: http://bugs.python.org/file37577/timeit_reject_invalid_statements.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18518> _______________________________________

1 0

[issue18518] return-ing within code timed with timeit.timeit causes wrong return value of timeit.timeit
by A.M. Kuchling 31 Dec '14

31 Dec '14

Changes by A.M. Kuchling <amk(a)amk.ca>: ---------- nosy: -akuchling _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18518> _______________________________________

1 0

[issue5901] missing meta-info in documentation pdf
by A.M. Kuchling 31 Dec '14

31 Dec '14

Changes by A.M. Kuchling <amk(a)amk.ca>: ---------- nosy: -akuchling _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue5901> _______________________________________

1 0

Re: [docs] 'codecs' module docs improvements (issue 19548)
by vadmium+py＠gmail.com 31 Dec '14

31 Dec '14

https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst File Doc/library/codecs.rst (right): https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:325: .. _surrogateescape: On 2014/12/26 01:21:35, zuo wrote: > Should be moved to the place above the ".. _error-handlers:" line (341). Still needs updating in the “default” branch. Not relevant for the 3.4 branch. https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:335: Each codec has to define four interfaces to make it usable as codec in Python: On 2014/12/26 01:21:35, zuo wrote: > Possible beginner's questions: is a codec an instance of :class:`Codec`? Or of > :class:`CodecInfo`? My understanding is a codec is a CodecInfo instance pointing to concrete classes implementing the (stateless) Codec, and/or stateful StreamReader/Writer, IncrementalDe/Encoder interfaces. Not sure on how many of these are mandatory though. > What does it mean that it define those *four* intefraces? > How is it related to the stateless/incremental/decoder/encoder and stream > writer/reader classes described below? Why here only *four* interfaces and not > *six* interfaces are mentioned? (i.e., what about *incremental encoder* and > *incremental decoder?*) https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst File Doc/library/codecs.rst (right): https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:24: bytes. Custom codecs may encode and decode between arbitrary types, but some Does this include non-sequence types? If so, the “length consumed” return value and the StreamReader class make no sense to me, and finalizing incremental codecs becomes more difficult. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:211: a text stream. Perhaps the last sentence is not needed, now that all these functions are introduced as being for binary files. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:382: The standard error handlers are implemented in the following functions: This is just “_Some_ standard error handlers”, since the surrogate handlers are omitted. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:420: Codec Objects On 2014/12/30 14:38:56, zuo wrote: > Still the relation between the `codec` term and the Codec class/objects is not > clear IMHO. Maybe changing the heading to “Stateless Codec Objects” would help? https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:625: *stream* must be a file-like object open for writing binary data. Did you mean to revert to “binary data” here? Patch v3 changed the wording here. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:829: :term:`text encoding` and recreating the On 2014/12/30 14:38:56, zuo wrote: > A see some term confusion here: the `text encoding` term is defined (in the > glossary) just as a *kind of* *codec*, buy *here* the words `encoding` and > `decoding` refer to activities (each being a reversal of the other) performed > *by* a *codec*. This was my sloppy wording, when I tried to introduce a link to the glossary. Maybe it should be added a couple sentences later: Transforming a string into a sequence of bytes is known as *encoding*, and recreating the string from the sequence of bytes is known as *decoding*. There are different methods for how this transformation can be done. (These methods are also called :term:`text encodings <text encoding>`.) https://bugs.python.org/review/19548/

1 0