Mailman 3 January 2015 - docs

[issue20487] Odd words in unittest.mock document.
by INADA Naoki Jan. 7, 2015

Jan. 7, 2015

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 Jan. 7, 2015

Jan. 7, 2015

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

bug in argparse docs?
by Jason Sachs Jan. 6, 2015

Jan. 6, 2015

In https://docs.python.org/2.7/library/argparse.html#action it says For more details, see Action. but there is no link anywhere. Is there a link missing to documentation on the Action class?

2 1

Ambiguity in python3.4 tutorial
by Borden Rhodes Jan. 6, 2015

Jan. 6, 2015

Good morning, In https://docs.python.org/3/tutorial/introduction.html#lists, there is an ambiguity. In section 3.1.3: Paragraph 3 reads: "All slice operations return a new list containing the requested elements." Paragraph 7 reads: "Assignment to slices is also possible, and this can even change the size of the list or clear it entirely." For a new user like me, paragraph 3 suggests that assigning anything to a slice would modify the new list, not the original list. Using the example in the tutorial, if letters = [a, b, c, d, e, f, g], and letters[2:5] returns the slice [c, d, e], then I would expect, under paragraph 3, that letters[2:5] = [C, D, E] would yield letters[2:5] = [C, D, E], since the array [C, D, E] would overwrite the new, 3 element array created by letters[2:5] which, under paragraph 3, is a copy of a slice of letters[] and not letters[] itself. As I said, I'm just starting out (but have experience in C++, Java & PHP), so I haven't checked the language specification for clarification. Perhaps the documentation could either remove the word 'all' in paragraph 3 so that it isn't as absolute or perhaps provide a reference or explanation in paragraph 7 which explains why my interpretation is incorrect. Please let me know if I can provide any assistance or clarification. With thanks, Borden Rhodes

1 0

Re: [docs] 'codecs' module docs improvements (issue 19548)
by vadmium+py＠gmail.com Jan. 6, 2015

Jan. 6, 2015

Addressing some of the comments in patch v5 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:211: a text stream. On 2014/12/31 10:53:25, vadmium wrote: > Perhaps the last sentence is not needed, now that all these functions are > introduced as being for binary files. Done. 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: On 2014/12/31 10:53:25, vadmium wrote: > This is just “_Some_ standard error handlers”, since the surrogate handlers are > omitted. Done. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newc… Doc/library/codecs.rst:420: Codec Objects On 2014/12/31 10:53:25, vadmium wrote: > 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? Done. 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. On 2014/12/31 10:53:25, vadmium wrote: > Did you mean to revert to “binary data” here? Patch v3 changed the wording here. Restored new wording in my v5 patch for 3.4 branch 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/31 10:53:25, vadmium wrote: > 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>`.) Added my new wording in new patch https://bugs.python.org/review/19548/

1 0

[issue23167] Marshal docs say format version is 3; actual format version is 4
by Dmitry Kazakov Jan. 4, 2015

Jan. 4, 2015

New submission from Dmitry Kazakov: Documentation on marshal module says that format version is 3, but Py_MARSHAL_VERSION is set to 4. Search for marshal-related issues gave me an idea that this is a documentation bug. ---------- assignee: docs@python components: Documentation files: marshal_doc.diff keywords: patch messages: 233429 nosy: docs@python, vlth priority: normal severity: normal status: open title: Marshal docs say format version is 3; actual format version is 4 versions: Python 3.4 Added file: http://bugs.python.org/file37598/marshal_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23167> _______________________________________

2 1

[issue20606] Operator Documentation Example doesn't work
by silentbat Jan. 4, 2015

Jan. 4, 2015

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

[issue17583] IDLE HOWTO
by Al Sweigart Jan. 4, 2015

Jan. 4, 2015

Changes by Al Sweigart <asweigart(a)gmail.com>: ---------- nosy: +Al.Sweigart _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17583> _______________________________________

1 0

[issue23153] Clarify Boolean Clause Results
by John Potelle Jan. 4, 2015

Jan. 4, 2015

New submission from John Potelle: >From v3.4 Tutorial section 5.7 It is possible to assign the result of a comparison or other Boolean expression to a variable. For example, >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance' >>> string1 or string2 or string3 'Trondheim' >>> bool(string1 or string2 or string3) True In most languages a Boolean clause (comparison) returns a Boolean or it's equivalent, not the last argument evaluated. Please add a reference to bool function (or some better? method) in this section for clarification. ---------- assignee: docs@python components: Documentation messages: 233330 nosy: docs@python, jpotelle priority: normal severity: normal status: open title: Clarify Boolean Clause Results type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23153> _______________________________________

4 7

[issue23116] Python Tutorial 4.7.1: Improve ask_ok() to cover more input values
by Carol Willing Jan. 3, 2015

Jan. 3, 2015

Carol Willing added the comment: @amylou Thank you for submitting this documentation suggestion about the Python Tutorial. This tutorial section, 4.7.1 Default Argument Values, tries to show that a function can have multiple input arguments which may be given default values. While the suggestion to use lower() does offer more robust input handling, it also adds some complexity to the example by introducing another function to a possibly new user. I do believe that the 'ask_ok' function could be improved by renaming the 'complaint' argument to something more positive, perhaps 'reminder'. I would also recommend replacing the error message 'uncooperative user' to something with a softer tone, perhaps 'invalid user response'. @amyluo If you are interested in working on documentation, section 6 of the Developer Guide is a handy resource (https://docs.python.org/devguide/docquality.html). ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python, willingc _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23116> _______________________________________

1 0