Mailman 3 November 2017 - docs

[issue30492] 'make clinic' does not work for out of tree builds / clinic.py is not in the devguide
by Gregory P. Smith 20 Dec '17

20 Dec '17

New submission from Gregory P. Smith: I never do in-tree builds anymore because they make me feel dirty and leave build artifacts cluttering up my source tree. make clinic does not work for out of tree builds. To reproduce: ~$ git clone ...cpython repo... ~$ mkdir build && cd build ~/build$ ../cpython/configure --with-pydebug ~/build$ make clinic ./python -E ./Tools/clinic/clinic.py --make ./python: can't open file './Tools/clinic/clinic.py': [Errno 2] No such file or directory Makefile:545: recipe for target 'clinic' failed make: *** [clinic] Error 2 Per https://docs.python.org/3/howto/clinic.html it looks like I can just manually run clinic.py on the files I have modified. Ideally the build system would take care of that for me. But all I really want is a single command that keeps me up to date. python3 Tools/clinic/clinic.py appears to be that command. Even if it isn't fixed for out of tree builds, use of clinic needs to be in the devguide. ---------- assignee: docs@python components: Argument Clinic, Documentation messages: 294604 nosy: docs@python, gregory.p.smith, larry priority: normal severity: normal stage: needs patch status: open title: 'make clinic' does not work for out of tree builds / clinic.py is not in the devguide type: compile error versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30492> _______________________________________

4 7

[issue32124] Document functions safe to be called before Py_Initialize()
by STINNER Victor 15 Dec '17

15 Dec '17

New submission from STINNER Victor <victor.stinner(a)gmail.com>: Follow-up of bpo-32086, bpo-32096 and "[Python-Dev] Python initialization and embedded Python" thread: https://mail.python.org/pipermail/python-dev/2017-November/150605.html I propose to explicitly list functions that can be safetely called before Py_Initialize(). This safety warranty must be part of the C API. Maybe we should even test all tests function in test_capi using Programs/_testembed, as we did for Py_DecodeLocale() and Py_SetProgramName() in commit 9e87e7776f7ace66baaf7247233afdabd00c2b44 ("pre_initialization_api" test). Attached PR adds proposed documentation. It also documents "global configuration variables" like Py_DebugFlag. ---------- assignee: docs@python components: Documentation messages: 306894 nosy: docs@python, eric.snow, ncoghlan, vstinner priority: normal severity: normal status: open title: Document functions safe to be called before Py_Initialize() versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32124> _______________________________________

4 12

[issue22671] Typo in class io.BufferedIOBase docs
by gigaplastik 12 Dec '17

12 Dec '17

New submission from gigaplastik: The online documentation for class io.BufferedIOBase states the following: "Besides, the read() method does not have a default implementation that defers to readinto()." According to the documentation for class io.RawIOBase (which the statement compares with) read() method actually defers to readall(), NOT readinto() as misleadingly stated. The same typo is present in help('io.BufferedIOBase') output and, very likely, in all 3.X line docs for this class. ---------- assignee: docs@python components: Documentation messages: 229677 nosy: docs@python, gigaplastik priority: normal severity: normal status: open title: Typo in class io.BufferedIOBase docs type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22671> _______________________________________

9 14

[issue31942] Document that support of start and stop parameters in the Sequence's index() is optional
by Serhiy Storchaka 12 Dec '17

12 Dec '17

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: Parameters start and stop were added to the Sequence.index() mixin method in 3.5 (see issue23086). But not all concrete implementations of the Sequence ABC support them (for example range.index() doesn't, see issue28197). This should be explicitly documented (including the docstring of Sequence.index). ---------- assignee: docs@python components: Documentation keywords: easy messages: 305547 nosy: docs@python, rhettinger, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Document that support of start and stop parameters in the Sequence's index() is optional type: behavior versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31942> _______________________________________

4 9

[issue29247] Document return value of epoll.poll
by Nathaniel Smith 11 Dec '17

11 Dec '17

New submission from Nathaniel Smith: The documentation for select.epoll.poll doesn't document the return value at all, which is somewhat important information :-) I think it's a list of (fd, eventmask) tuples? https://docs.python.org/3.7/library/select.html#select.epoll.poll ---------- assignee: docs@python components: Documentation messages: 285285 nosy: docs@python, njs priority: normal severity: normal status: open title: Document return value of epoll.poll versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29247> _______________________________________

5 6

Incorrect Syntax
by epiphany＠tutanota.com 04 Dec '17

04 Dec '17

https://docs.python.org/3/tutorial/stdlib2.html#output-formatting >>> import pprint>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',... 'yellow'], 'blue']]]...>>> pprint.pprint(t, width=30) It doesn't work. There's one "]" too much in blue... It should look like this: >>> import pprint>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',... 'yellow'], 'blue']]...>>> pprint.pprint(t, width=30) Then it works.

2 1

Re: [docs] Incorrect statement in section 8.3 of Python Tutorial
by Randy Duncan 30 Nov '17

30 Nov '17

Hi Zach, Thanks for the response! I just retried it and also got the B B B that the doc says I should get. Which is probably a good reason to remind myself not to try to correct things when I'm a newbie. Except of course, who else reads tutorials, except newbies? Unfortunately, my original work was all done in interactive mode, but after playing around a bit, I suspect I might have defined all my classes with Exception as the parm rather than the previous class. ie: class B(Exception): class C(Exception): class D(Exception): When I do that, I get the behavior I reported. Sorry to have wasted your time. I'm loving Python so far! Randy ______________________________________________________________ Randy Duncan, PMP PMI-ACP CSM Test Architect, IBM Cloud Infrastructure Core Fabric Team 14001 Dallas Parkway, Suite M100, Dallas, TX 75240 214-873-8316 Office | 469-360-7232 Cell | randy.duncan(a)ibm.com From: Zachary Ware <zachary.ware+pydocs(a)gmail.com> To: docs <docs(a)python.org> Cc: Randy Duncan <randy.duncan(a)ibm.com> Date: 11/30/2017 02:02 PM Subject: Re: [docs] Incorrect statement in section 8.3 of Python Tutorial Sent by: zachary.ware(a)gmail.com Hi Randy, On Mon, Nov 27, 2017 at 1:19 PM, Randy Duncan <randy.duncan(a)ibm.com> wrote: > I believe I found an erroneous statement in the Python tutorials. > > In section 8.3 found here ( https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.python.org_3.6_tu… ) > > There is a section showing how to handle exceptions which works as > advertised: > > > However, the next line in the tutorial state this: > > > Note that if the except clauses were reversed (with except B first), it > would have printed B, B, B — the first matching except clause is triggered. > > > I re-entered the example and reversed the except clauses, and got this > result which does not match the statement: Thanks for the report! However, I just tried it myself and got the output predicted by the docs. Can you show how you defined B, C, and D? Regards, -- Zach

1 0

expression and order of evaluation example
by John Sullivan 30 Nov '17

30 Nov '17

Hi – a question about something in the docs. In order of math operations we all use PEMDAS with parentheses coming first. On the page related to that in the docs: https://docs.python.org/3/reference/expressions.html I find this example in section 6.15 – Evaluation Order, which states that in the examples given the expressions will be evaluated in the arithmetic order of their suffixes: expr1 + expr2 * (expr3 - expr4) I thought with PEMDAS being the rule (for that simple expression) that the order of operations would actually be: expr4 + expr3 * (expr1 – expr2) since the parentheses should force that operation (item1 – item2) to happen first, followed by the multiplication by item3 and finally adding item4. So which is correct? As listed(1,2,3,4) or the version I’ve typed below that (4,3,1,2)? Follow-up question – to do this PEMDAS and other evaluation is it correct to assume that Python keeps rescanning the expression from left to right (with the exception of exponentiation) over and over while it reduces down the values represented until it has a single workable string to process into its single final value? Thanks, John Sullivan Systems Engineer Mercury Paper, Inc. Office: (540) 465-7733

1 0

Incorrect statement in section 8.3 of Python Tutorial
by Randy Duncan 30 Nov '17

30 Nov '17

I believe I found an erroneous statement in the Python tutorials. In section 8.3 found here (https://docs.python.org/3.6/tutorial/errors.html ) There is a section showing how to handle exceptions which works as advertised: However, the next line in the tutorial state this: Note that if the except clauses were reversed (with except B first), it would have printed B, B, B — the first matching except clause is triggered. I re-entered the example and reversed the except clauses, and got this result which does not match the statement: Best regards, Randy Duncan ______________________________________________________________ Randy Duncan, PMP PMI-ACP CSM Test Architect, IBM Cloud Infrastructure Core Fabric Team 14001 Dallas Parkway, Suite M100, Dallas, TX 75240 214-873-8316 Office | 469-360-7232 Cell | randy.duncan(a)ibm.com

2 1

[issue32160] lzma documentation: example to XZ compress file on disk
by Daniel Himmelstein 28 Nov '17

28 Nov '17

Daniel Himmelstein <daniel.himmelstein(a)gmail.com> added the comment: > we could consider an API addition Just brainstorming here... perhaps an API addition would be most appropriate in the shutil module (https://docs.python.org/3.6/library/shutil.html) which already contains shutil.make_archive and shutil.unpack_archive. One could imagine shutil.compress and shutil.decompress that took a format argument to specify the compression type. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32160> _______________________________________

1 0