Mailman 3 May 2016 - docs

[issue27000] improve document of filter
by Xiang Zhang May 12, 2016

May 12, 2016

New submission from Xiang Zhang: I think filter's doc can be improved[1]: 1. It doesn't mention ``bool``. ``bool`` is treated the same way as ``None``. It is not called. But this is not mentioned. 2. 'the identity function is assumed' is confusing, at least for me. It looks like when ``None`` is passed, *function* is set to a default func, lambda x: x. Then *function* is called and we identify the return value True or False. But this is not the truth. There is no default value and no function is applied. I think this should be deleted. [1] https://docs.python.org/3/library/functions.html#filter ---------- assignee: docs@python components: Documentation files: filter_doc.patch keywords: patch messages: 265325 nosy: docs@python, xiang.zhang priority: normal severity: normal status: open title: improve document of filter versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file42818/filter_doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27000> _______________________________________

5 10

[issue26997] Docs for pdb should note that __future__ magic doesn't work
by Martin Jones May 11, 2016

May 11, 2016

New submission from Martin Jones: when debugging a program at the pdb prompt, attempting to import from the __future__ module appears successful, but actually doesn't work: (Pdb) from __future__ import division (Pdb) 2/3 0 This leads to inconsistencies between statements evaluated on the pdb prompt and those evaluated in the program, which can hamper debugging. It would be good to have a note added to the 2.7 documentation for pdb along the lines of: Note: importing from the __future__ module does not work under pdb. ---------- assignee: docs@python components: Documentation messages: 265300 nosy: Martin Jones, docs@python priority: normal severity: normal status: open title: Docs for pdb should note that __future__ magic doesn't work type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26997> _______________________________________

1 0

[issue23921] Standardize documentation whitespace, formatting
by James Edwards May 10, 2016

May 10, 2016

New submission from James Edwards: I realize this is a huge patch, I'd be happy to split it to multiple little patches (one per file, one per documentation directory, etc.) to make things easier. Just let me know. The patch attempts to do a few things (with exceptions, as noted below): 1. Standardize leading whitespace in block bodies (4 spaces per level) 2. Enforce >= 2 spaces between code and inline comment 3. In interactive interpreter snippets, ensures lines meant to be entered are preceded by '>>> ' or '... ' 4. Inline whitespace standardization (following a liberal / lenient (not strict) PEP-8 testing) Scanning the documentation, extracting the code snippets, and testing them for PEP-8 compliance was done with a script, but all adjustments were done by hand. This means that there remain some code that fails the lenient PEP-8 checks that I used. For example, code at [1] ("How to write obfuscated one liners") obviously threw errors, but because of the context of the snippet and the use it serves in the documentation, it was left it unchanged. Similarly, there are (intentionally) poorly formatted snippets in [2] ("Lexical Analysis") that were also left unchanged. Since these changes were applied by hand, I was able to ignore situations where things that would normally raise warnings. I erred on the side of leaving the documentation examples unchanged, and strived to make only innocuous changes. I made no attempt to change the functionality or semantics of any of the snippets. The only changes I made were "harmless" formatting. None of the changes will affect the function or output of the snippets. What the changes do, however, is give a consistency to the documentation that will allow readers to become more comfortable with the structure of the language and improve readability. [1] https://docs.python.org/3/faq/programming.html#is-it-possible-to-write-obfu… [2] https://docs.python.org/3/reference/lexical_analysis.html#indentation [3] http://pep8.readthedocs.org/en/latest/intro.html In addition to the checks that are ignored by default by the pep8[3] module for not being unanimously accepted: E121 # continuation line under-indented for hanging indent E123 # closing bracket does not match indentation of opening bracket’s line E126 # continuation line over-indented for hanging indent E133 # closing bracket is missing indentation E226 # missing whitespace around arithmetic operator E241 # multiple spaces after ‘,’ E242 # tab after ‘,’ E704 # multiple statements on one line (def) The following checks were "globally" ignored in my script, though many others were conditionally ignored by the script or by myself. ignore.append('W292') # no newline at end of file ignore.append('E302') # expected 2 blank lines, found 0 ignore.append('E401') # multiple imports on one line ignore.append('W391') # blank line at end of file ignore.append('E231') # missing whitespace after ',' ignore.append('E114') # indentation is not multiple of four (comment) ignore.append('E116') # unexpected indentation (comment) While the patch diffstat is: 67 files changed, 450 insertions(+), 412 deletions(-) Ignoring all whitespace changes, the diffstat is only: 10 files changed, 118 insertions(+), 114 deletions(-) The majority of these remaining changes fix the inconsistency of interactive interpreter snippets, where, within the same snippet, some lines have '>>> ' while others are missing it, or the '... ' continuation prompt. Let me know if you need anything from me (such as splitting this patch up) to help get it merged. Thanks. ---------- assignee: docs@python components: Documentation files: docsdiff.diff keywords: patch messages: 240540 nosy: docs@python, jedwards priority: normal severity: normal status: open title: Standardize documentation whitespace, formatting type: enhancement Added file: http://bugs.python.org/file38903/docsdiff.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23921> _______________________________________

7 18

Re: [docs] Standardize documentation whitespace, formatting (issue 23921)
by storchaka＠gmail.com May 10, 2016

May 10, 2016

http://bugs.python.org/review/23921/diff/14579/Doc/faq/library.rst File Doc/faq/library.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/faq/library.rst#newcode7… Doc/faq/library.rst:747: On 2016/01/07 02:41:26, vadmium wrote: > Could probably drop this new blank line Done. http://bugs.python.org/review/23921/diff/14579/Doc/faq/programming.rst File Doc/faq/programming.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/faq/programming.rst#newc… Doc/faq/programming.rst:668: >>> print(b) On 2016/03/02 08:04:04, Georg wrote: > On 2016/01/07 02:41:26, vadmium wrote: > > Why not add prompts to the lines above as well? > > Yes, link this it's a bit inconsistent. Done. http://bugs.python.org/review/23921/diff/14579/Doc/howto/logging-cookbook.r… File Doc/howto/logging-cookbook.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/howto/logging-cookbook.r… Doc/howto/logging-cookbook.rst:742: root.setLevel(logging.DEBUG) # send all messages, for demo; no other level or filter logic applied. On 2016/03/02 08:04:04, Georg wrote: > this is probably too long a line (e.g. for PDF output), better move the comment > above the code Done. http://bugs.python.org/review/23921/diff/14579/Doc/howto/urllib2.rst File Doc/howto/urllib2.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/howto/urllib2.rst#newcod… Doc/howto/urllib2.rst:178: values = {'name' : 'Michael Foord', On 2016/03/02 08:04:04, Georg wrote: > could also remove the spaces before ':' as well. Done. http://bugs.python.org/review/23921/diff/14579/Doc/library/abc.rst File Doc/library/abc.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/abc.rst#newcode92 Doc/library/abc.rst:92: On 2016/01/07 02:41:26, vadmium wrote: > FWIW I think the existing compact form is fine. The methods don’t have any > substance, so separating them doesn’t buy much. But if you want to make the > style consistent with MyIterable, you need a blank line above __getitem__() as > well. Done. Removed empty lines. http://bugs.python.org/review/23921/diff/14579/Doc/library/locale.rst File Doc/library/locale.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/locale.rst#newco… Doc/library/locale.rst:473: >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut On 2016/03/02 08:04:04, Georg wrote: > keep only 2 spaces, the line is already long Done. http://bugs.python.org/review/23921/diff/14579/Doc/library/multiprocessing.… File Doc/library/multiprocessing.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/multiprocessing.… Doc/library/multiprocessing.rst:2071: print(result.get(timeout=1)) # prints "100" unless your computer is *very* slow On 2016/03/02 08:04:04, Georg wrote: > these lines are also too long. Will be addressed in separate issue. Changes for this example are reverted. http://bugs.python.org/review/23921/diff/14579/Doc/library/optparse.rst File Doc/library/optparse.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/optparse.rst#new… Doc/library/optparse.rst:1827: [...] On 2016/03/02 08:04:04, Georg wrote: > replace by a single ellipsis, I don't think we're using that style anywhere else Done. http://bugs.python.org/review/23921/diff/14579/Doc/library/tokenize.rst File Doc/library/tokenize.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/tokenize.rst#new… Doc/library/tokenize.rst:216: if toknum == NUMBER and '.' in tokval: # replace NUMBER tokens On 2016/03/02 08:04:04, Georg wrote: > no, keep shorter line Done. http://bugs.python.org/review/23921/diff/14579/Doc/library/urllib.request.r… File Doc/library/urllib.request.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/library/urllib.request.r… Doc/library/urllib.request.rst:1105: ... data=b'This data is passed to stdin of the CGI') On 2016/03/02 08:04:04, Georg wrote: > this is also a case where the longer line may hurt Done. http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst File Doc/whatsnew/3.2.rst (left): http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst#oldcode… Doc/whatsnew/3.2.rst:502: On 2016/01/07 02:41:26, vadmium wrote: > You could keep the blank line here to mirror the interactive interpreter better Done. http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst File Doc/whatsnew/3.2.rst (right): http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst#newcode… Doc/whatsnew/3.2.rst:1107: ... b'G3805 storeroom Main chassis ' On 2016/01/07 02:41:26, vadmium wrote: > Why not a four-space indent? Done. http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst#newcode… Doc/whatsnew/3.2.rst:1540: >>> os.chdir('mydata') # change to the source directory On 2016/03/02 08:04:04, Georg wrote: > again, too long lines here. Done. http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst#newcode… Doc/whatsnew/3.2.rst:1555: ... name = 'xz', On 2016/01/07 02:41:26, vadmium wrote: > I think you could drop the space around the equal signs and make it name='xz', > etc. Done. http://bugs.python.org/review/23921/diff/14579/Doc/whatsnew/3.2.rst#newcode… Doc/whatsnew/3.2.rst:1882: On 2016/01/07 02:41:26, vadmium wrote: > Add an extra ellipsis to imitate the interpreter better Done. http://bugs.python.org/review/23921/

1 0

[issue26986] Enhance PyFunction_New documentation
by Roundup Robot May 10, 2016

May 10, 2016

Roundup Robot added the comment: New changeset bfc4c57a0986 by Benjamin Peterson in branch '3.5': improve PyFunction_New docs (closes #26986) https://hg.python.org/cpython/rev/bfc4c57a0986 New changeset 71afeb15f617 by Benjamin Peterson in branch 'default': merge 3.5 (#26986) https://hg.python.org/cpython/rev/71afeb15f617 ---------- nosy: +python-dev resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26986> _______________________________________

1 0

[issue26986] Enhance PyFunction_New documentation
by Xiang Zhang May 9, 2016

May 9, 2016

Changes by Xiang Zhang <angwerzx(a)126.com>: ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26986> _______________________________________

1 0

[issue26512] Vocabulary: Using "integral" in library/stdtypes.html
by Julien May 8, 2016

May 8, 2016

New submission from Julien: o/ TL;DR: I think the various usages of "Integral" in https://docs.python.org/3.5/library/stdtypes.html#numeric-types-int-float-c… are either wrong or too hard to understand and should be rewriten as "int". While translating the documentation I found the sentence "x truncated to Integral" in https://docs.python.org/3.5/library/stdtypes.html#numeric-types-int-float-c… for the `math.floor(x)` method. By "Integral" I assume you're speaking about the ABC `numbers.Integral`, whish is already not clear, but the capital I helps. According to pydoc and PEP3141, the `numbers.Integral` ABC inherits from Rational, which inherits from Real which inherits from Complex which inherits from Number. So number is the broader ABC and integral the opposite, the representation of an integer. I do _NOT_ assume that someone reading the stdtypes.html section is aware of those ABCs, so I don't think it's nice for them to use them without linking to them. So I infer than "x truncated to integral" means "x truncated to the nearest integer". Which is far more readable. Two lines after, I found "The greatest integral float <= x" for `math.floor(x)` which is less readable, no capital I to `integral` and what is an `integral float` ? Also the documentation of `math.floor` states an `int` is returned (as the doc for math.trunc states an Integral is returned). So there's two possibilities here: - The doc uses vocabulary and phrase structures I don't understand and "integral float" actually mean something. - The doc is not clear In both cases, I suggest to either transform "integral" usages to a link to :class:`numbers.Integral` or simply speaking of "int" here. Context: I'm translating the documentation in French, I achieved `tutorial.html` and `functions.html` and it's until here the hardest sentence to understand (others were simply wrong like in http://bugs.python.org/issue26029) or understandable, so even if those structures are semantically and gramatically correct, they're clearly one of the hardest to understand, which is sad as we're only speaking of rounding numbers. I mean, if there's a goal to sand away spikes in doc readability, this one is a big one. So, can an english native speaker can enlighten me about this ? Bests, ---------- assignee: docs@python components: Documentation messages: 261380 nosy: docs@python, sizeof priority: normal severity: normal status: open title: Vocabulary: Using "integral" in library/stdtypes.html type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26512> _______________________________________

8 24

[issue26736] Use HTTPS protocol in links
by Serhiy Storchaka May 8, 2016

May 8, 2016

New submission from Serhiy Storchaka: Proposed patch makes links in the docs to use the HTTPS protocol if possible. All changed links are tested manually. ---------- assignee: docs@python components: Documentation files: links_https.patch keywords: patch messages: 263197 nosy: alex, christian.heimes, docs@python, dstufft, georg.brandl, giampaolo.rodola, janssen, pitrou, serhiy.storchaka, tim.golden priority: normal severity: normal stage: patch review status: open title: Use HTTPS protocol in links type: security versions: Python 2.7, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file42435/links_https.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26736> _______________________________________

4 8

[issue26156] Bad name into power operator syntax
by Chema Cortés May 8, 2016

May 8, 2016

New submission from Chema Cortés: The documentation erroneously changes "primary" for "away" in the power operator syntax: https://docs.python.org/3.6/reference/expressions.html#the-power-operator https://docs.python.org/3.5/reference/expressions.html#the-power-operator ---------- assignee: docs@python components: Documentation messages: 258596 nosy: Chema Cortés, docs@python priority: normal severity: normal status: open title: Bad name into power operator syntax versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26156> _______________________________________

8 19

[issue18730] suffix parameter in NamedTemporaryFile silently fails when not prepending with a period
by Terry J. Reedy May 7, 2016

May 7, 2016

Terry J. Reedy added the comment: Correct. The doc I quoted was for the unlying mkstemp function. I should have said so even though this fact was easily discovered. So by docstring, I meant the one for mkstemp also, which is currently 27 lines. The docstring for the high level functions should not change. I proposed to shorten the docstring by combining the sentences for prefix and suffix, while adding a bit of info. I decided to withdraw this suggestion and close this issue. ---------- assignee: docs@python -> terry.reedy resolution: -> rejected stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18730> _______________________________________

1 0