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 … [View More]

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 … [View More]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> _______________________________________ [View Less]

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 … [View More]

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/… [View More]

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.… [View More]

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 … [View More]

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 … [View More]

1 0