Mailman 3 August 2014 - docs

[issue19934] collections.Counter.most_common does not document `None` as acceptable input.
by Matthew Gilson May 13, 2015

May 13, 2015

New submission from Matthew Gilson: Reading the source for collections.Counter.most_common, the docstring mentions that `n` can be `None` or omitted, but the online documentation does not mention that `n` can be `None`. ---------- assignee: docs@python components: Documentation messages: 205648 nosy: docs@python, mgilson priority: normal severity: normal status: open title: collections.Counter.most_common does not document `None` as acceptable input. _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19934> _______________________________________

4 7

[issue15329] clarify which deque methods are thread-safe
by Chris Jerdonek April 25, 2015

April 25, 2015

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think it would help to clarify which collections.deque methods are thread-safe: http://docs.python.org/dev/library/collections.html?highlight=deque#collect… Currently, the documentation says that "Deques support thread-safe, memory efficient appends and pops from either side...," but it isn't obvious if this is meant to apply to all methods, or just the methods named append*() and pop*(). For example, is rotate() thread-safe? The illustration given of d.appendleft(d.pop()) seems like it could be interleaved. ---------- assignee: docs@python components: Documentation keywords: easy messages: 165275 nosy: cjerdonek, docs@python, rhettinger priority: normal severity: normal status: open title: clarify which deque methods are thread-safe versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15329> _______________________________________

6 10

[issue16574] clarify policy on updates to final peps
by Chris Jerdonek April 22, 2015

April 22, 2015

New submission from Chris Jerdonek: This issue is to clarify the policy in PEP 1 regarding non-substantive changes to PEPs in the Final state (minor clarifications, rephrasings, etc). Currently, PEP 1 says, "In general, Standards track PEPs are no longer modified after they have reached the Final state." (from http://www.python.org/dev/peps/pep-0001/#pep-maintenance ) However, others have pointed out that minor clarifications and rephrasings are in fact allowed: http://bugs.python.org/issue15990#msg176575 The updated wording should also state the policy or process regarding such changes (who is allowed to make them and whether and from whom approval is needed to make such changes, etc). ---------- assignee: docs@python components: Documentation messages: 176598 nosy: barry, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, goodger, ncoghlan priority: normal severity: normal status: open title: clarify policy on updates to final peps type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________

11 21

[issue15183] it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count
by Tshepang Lekhonkhobe April 21, 2015

April 21, 2015

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: I looked at 'python -m time -h' and the timeit doc, and it was not clear to me (after a quick read) that the statement(s) inside --setup option and setup keyword argument weren't included in the speed test. I had to check for myself by writing code. ---------- assignee: docs@python components: Documentation messages: 163999 nosy: docs@python, tshepang priority: normal severity: normal status: open title: it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15183> _______________________________________

4 4

[issue13386] Document documentation conventions for optional args
by Ezio Melotti April 20, 2015

April 20, 2015

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: AFAIU the conventions for optional argument in the doc are as follow: If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example: str.splitlines(keepends=False) If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. This should apply only to some C functions, for example: str.strip([chars]) The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted. These rules apply to both Python 2 and Python 3. A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function. ---------- assignee: docs@python components: Documentation messages: 147469 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: needs patch status: open title: Document documentation conventions for optional args versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13386> _______________________________________

10 29

[issue15566] tarfile.TarInfo.frombuf documentation is out of date
by Sebastian Ramacher April 19, 2015

April 19, 2015

New submission from Sebastian Ramacher: tarfile.TarInfo.frombuf has gained two more parameters: encoding and errors. The documentation of frombuf claims that the only parameter is buf, which is not true anymore. ---------- assignee: docs@python components: Documentation messages: 167553 nosy: docs@python, sebastinas priority: normal severity: normal status: open title: tarfile.TarInfo.frombuf documentation is out of date versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15566> _______________________________________

6 5

[issue19933] Round default argument for "ndigits"
by João Bernardo April 15, 2015

April 15, 2015

New submission from João Bernardo: >From the docs for built-in function "round": "If ndigits is omitted, it defaults to zero" (http://docs.python.org/3/library/functions.html#round) But, the only way to get an integer from `round` is by not having the second argument (ndigits): >>> round(3.5) 4 >>> round(3.5, 1) 3.5 >>> round(3.5, 0) 4.0 >>> round(3.5, -1) 0.0 >>> round(3.5, None) Traceback (most recent call last): File "<pyshell#6>", line 1, in <module> round(3.5, None) TypeError: 'NoneType' object cannot be interpreted as an integer Either the docs are wrong or the behavior is wrong. I think it's easier to fix the former... But also there should be a way to make round return an integer (e.g. passing `None` as 2nd argument) ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 205647 nosy: JBernardo, docs@python priority: normal severity: normal status: open title: Round default argument for "ndigits" versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19933> _______________________________________

7 22

[issue22046] ZipFile.read() should mention that it might throw NotImplementedError
by Jason Heeris April 14, 2015

April 14, 2015

New submission from Jason Heeris: As per issue 5701, the zipfile.ZipFile.read() method will throw a NotImplementedError if the compression scheme is not supported. However, there is no mention of this possibility in the documentation for the read() method. I would suggest, say, "Calling read() on a ZipFile that uses an unsupported compression scheme (eg. implode) will raise a NotImplementedError." It looks like you can use the testzip() method to check that this won't happen (ie. after you open the file but before you extract an entry). If that is really the expected way to check for this kind of condition, it would be nice to mention that too (under either method). ---------- assignee: docs@python components: Documentation messages: 223737 nosy: detly, docs@python priority: normal severity: normal status: open title: ZipFile.read() should mention that it might throw NotImplementedError type: enhancement versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22046> _______________________________________

6 15

[issue21146] update gzip usage examples in docs
by Wolfgang Maier April 14, 2015

April 14, 2015

New submission from Wolfgang Maier: The current documentation of the gzip module should have its section "12.2.1. Examples of usage" updated to reflect the changes made to the module in Python3.2 (https://docs.python.org/3.2/whatsnew/3.2.html#gzip-and-zipfile). Currently, the recipe given for gz-compressing a file is: import gzip with open('/home/joe/file.txt', 'rb') as f_in: with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out: f_out.writelines(f_in) which is clearly sub-optimal because it is line-based. An equally simple, but more efficient recipe would be: chunk_size = 1024 with open('/home/joe/file.txt', 'rb') as f_in: with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out: while True: c = f_in.read(chunk_size) if not c: break d = f_out.write(c) Comparing the two examples I find a >= 2x performance gain (both in terms of CPU time and wall time). In the inverse scenario of file *de*-compression (which is not part of the docs though), the performance increase of substituting: with gzip.open('/home/joe/file.txt.gz', 'rb') as f_in: with open('/home/joe/file.txt', 'wb') as f_out: f_out.writelines(f_in) with: with gzip.open('/home/joe/file.txt.gz', 'rb') as f_in: with open('/home/joe/file.txt', 'wb') as f_out: while True: c = f_in.read(chunk_size) if not c: break d = f_out.write(c) is even higher (4-5x speed-ups). In the de-compression case, another >= 2x speed-up can be achieved by avoiding the gzip module completely and going through a zlib.decompressobj instead, but of course this is a bit more complicated and should be documented in the zlib docs rather than the gzip docs (if you're interested, I could provide my code for it though). Using the zlib library compression/decompression speed gets comparable to linux gzip/gunzip. ---------- assignee: docs@python components: Documentation messages: 215440 nosy: docs@python, wolma priority: normal severity: normal status: open title: update gzip usage examples in docs type: performance versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21146> _______________________________________

6 10

[issue19121] Documentation guidelines enhancements
by anatoly techtonik April 14, 2015

April 14, 2015

New submission from anatoly techtonik: I'll raise some points and then suggest how to fix that. issue19060 it appeared that list of functions that subprocess replaces imbues readers with uncertainty, because this list is not complete. Current http://docs.python.org/devguide/documenting.html guide doesn't pay attention that information should be "complete and unambiguous". issue19060 is a good example of completeness requirement - user should not be left guessing what other functions can be or can not be replaced by subprocess. Unambiguous means that there should also be answer why they can or can not be replaced. For subprocess this info is partially provided in "replacing older functions" chapter. There also should not be a place for subjective judgement, fear and desperation. If something can not be done with subprocess, users should not be discouraged (left in fear) to use older functions. If there are valid points where subprocess is not good, they should be described in advanced section. If the description is too long to read, it should be linked. Somebody may raise the point that subprocess docs is not the best place for such list. But between choice to be complete and structured, the former should take precedence. When documentation is complete enough, it's text can be restructured. This further raises a point about structure of docs. Both main docs and guidelines itself. Main docs structure. The more unambiguous, complete and concise documentation is, the better it is for understanding. Currently our docs really miss overviews and summaries. Some may argue that there is no place for that in official docs, especially if such summaries will contain info about history and changes between Python versions. But I'd say that if there is no place, we need to find it for them. Just two examples. MSDN and Python Cookbook both are examples of perfect documentation and these both include overview chapters before function reference. When where is a critical mass of info related to child process execution and management, it is worth to make an overview. Guidelines structure. ToC. Sphinx ToCs are too narrow - they are hard to read. If ToC is present in side panel for navigation, it is not the reason not to include it below the page header for human readers to see the structure of the doc. I find it extremely hard (unnatural) to scan the side panel for the doc structure. This should be split between markup and content guidelines. Right now the structure of docs is: 7. Documenting Python 7.1. Introduction 7.2. Style guide 7.2.1. Use of whitespace 7.2.2. Footnotes 7.2.3. Capitalization 7.2.4. Affirmative Tone 7.2.5. Economy of Expression 7.2.6. Code Examples 7.2.7. Code Equivalents 7.2.8. Audience 7.3. reStructuredText Primer 7.3.1. Paragraphs 7.3.2. Inline markup 7.3.3. Lists and Quotes 7.3.4. Source Code 7.3.5. Hyperlinks 7.3.5.1. External links 7.3.5.2. Internal links 7.3.6. Sections 7.3.7. Explicit Markup 7.3.8. Directives 7.3.9. Footnotes 7.3.10. Comments 7.3.11. Source encoding 7.3.12. Gotchas 7.4. Additional Markup Constructs 7.4.1. Meta-information markup 7.4.2. Module-specific markup 7.4.3. Information units 7.4.4. Showing code examples 7.4.5. Inline markup 7.4.6. Cross-linking markup 7.4.7. Paragraph-level markup 7.4.8. Table-of-contents markup 7.4.9. Index-generating markup 7.4.10. Grammar production displays 7.4.11. Substitutions 7.5. Differences to the LaTeX markup 7.5.1. Inline markup 7.5.2. Information units 7.5.3. Structure 7.6. Building the documentation 7.6.1. Using make 7.6.2. Without make As you may see the 90% of the ToC is markup reference. Some topics like "Hyperlinks" are oversplit. Making two chapter for just one sentence is an obsession with structure. That's ok for coding, but for readability I would just make it into a list in one chapter, renamed to "Linking" and merged "cross-linking markup" section into it. 7.2.3. Capitalization 7.2.4. Affirmative Tone 7.2.5. Economy of Expression 7.2.6. Code Examples As you may see, the "Content writing" is perfectly mixed with "Content formatting" into the mix of rules for proper whitespace formatting. This perfectly characterizes us coders, who often mix the concept of "good code which is bug-free" with concept of "good code which is PEP-8 compliant". I mean that it leaves expression that most of the document is about rules, regulations and nitpicking about how you should format the text, not how you should write. Let's make this unambiguous - "Content" of documentation is essential info that readers need to know. "Format" of docs is the markup, whitespace, examples, footnotes and other stuff. "Content guidelines" say that you should insert footnotes, "Format guidelines" show how to do this. "Content guidelines" should not distract from the content aspects. So, the "Style Guide" should be split into "Content Writing" and "Formatting Guidelines" [ ]. Or moves into separate file at all. The "Content Writing" chapter. Should include chapter that docs should be complete and unambiguous, with the points raised above, probably with a link to the linked issue. I don't get what "affirmative tone" is. I don't get it, because header "affirmative tone" for non-native non-speaker doesn't contain the answer what and why. To me chapters like "avoid uncertainty" are more concise and valid. "Documentation is a place for facts. Make sure that facts are complete. That after reading the documentation users are not left with doubts and fears. Make sure that if is there is a recommendation, there is also a link to reasons." "establishing confident knowledge" and "affirmative tone" are phrases from NLP psychotherapy courses. It looks like guideline to program the readers for positive emotions, not to provide them with facts. I am not saying that docs should be dry and lawfully correct. Just the focus should be on the side of facts. I hope that this feedback is useful. ---------- assignee: docs@python components: Devguide, Documentation messages: 198571 nosy: docs@python, ezio.melotti, techtonik priority: normal severity: normal status: open title: Documentation guidelines enhancements _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19121> _______________________________________

5 5