Mailman 3 December 2017 - docs

[issue19847] Setting the default filesystem-encoding
by STINNER Victor Dec. 18, 2017

Dec. 18, 2017

STINNER Victor <victor.stinner(a)gmail.com> added the comment: Follow-up: the PEP 538 (bpo-28180) and PEP 540 (bpo-29240) have been accepted and implemented in Python 3.7. Python 3.7 will now use UTF-8 by default for the POSIX locale, and the encoding can be forced to UTF-8 using -X utf8 option. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue19847> _______________________________________

1 0

Confusing API in Threading module.
by Dong Uk Ju Dec. 18, 2017

Dec. 18, 2017

Dear Python Managers, While reading the API for Threading module, I noticed that explanation of Lock.acquire() is really confusing. Here I attach the original statement. (Python 2) Lock.acquire([blocking])<https://docs.python.org/2/library/threading.html#threading.Lock.acquire> Acquire a lock, blocking or non-blocking. When invoked with the blocking argument set to True (the default), block until the lock is unlocked, then set it to locked and return True. When invoked with the blocking argument set to False, do not block. If a call with blocking set to True would block, return False immediately; otherwise, set the lock to locked and return True. (Python 3) acquire(blocking=True, timeout=-1)¶<https://docs.python.org/3/library/threading.html#threading.Lock.acquire> Acquire a lock, blocking or non-blocking. When invoked with the blocking argument set to True (the default), block until the lock is unlocked, then set it to locked and return True. When invoked with the blocking argument set to False, do not block. If a call with blocking set to Truewould block, return False immediately; otherwise, set the lock to locked and return True. When invoked with the floating-point timeout argument set to a positive value, block for at most the number of seconds specified by timeout and as long as the lock cannot be acquired. A timeout argument of -1 specifies an unbounded wait. It is forbidden to specify a timeout when blocking is false. The return value is True if the lock is acquired successfully, False if not (for example if the timeoutexpired). Both version have statement "When invoked with the blocking argument set to False, do not block. If a call with blocking set to True would block, return False immediately". The second sentence confuses a lot. What happen if a call with blocking set to False would block ?? >From my insight, it might also return False immediately and will not block or wait for other working thread. If my understanding is wrong, prior acquire call's blocking argument matters for later call of acquire. Then, there should be 4 cases, 1) acquire(True) on acquire(True) 2) acquire(True) on acquire(False) 3) acquire(False) on acquire(True) 4) acquire(False) on acquire(False). I don't think this works in this way, besides API doesn't specifies those cases. If my understanding is right,(Prior interpretation is right), I recommend to revise the sentence to "When invoked with the blocking argument set to False, do not block. If acquire() is called with blocking set to False while another thread is working on it(currently locked status), return False immediately." Please kindly consider this for better python. Thank you. Sincerely, Donguk Ju.

1 0

[issue32349] Add detailed return value information for set.intersection function
by 양유석 Dec. 18, 2017

Dec. 18, 2017

New submission from 양유석 <ileixe(a)gmail.com>: I think it's intentional behavior seems to be minor though. At a glance, I assume that a.set(b) should return items in a. But I found out the implementation always return items in smaller set. There is no issue for common case, but custom class can make a trouble. So, I think additional information of return value is helpful. ---------- assignee: docs@python components: Documentation messages: 308484 nosy: docs@python, 양유석 priority: normal severity: normal status: open title: Add detailed return value information for set.intersection function type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32349> _______________________________________

3 3

[issue32353] Add docs about Embedding with an frozen module limitation.
by Decorater Dec. 17, 2017

Dec. 17, 2017

New submission from Decorater <seandhunt_7(a)yahoo.com>: It seems that 1 thing that bites me is that there is no section on the embedding docs about limitations to using frozen modules in them. So lets say for example your program has this like in the main function on an embedded python: ```c PyRun_SimpleString("import mymodule"); ``` And lets say ``mymodule`` is supposed to be an frozen module in that embedded interpreter named ``myprogram`` It would fail to work because it wont be able to find ``mymodule`` when it really should. This doc change should help fix that senerio and hopefully suggest an fix to that senerio as well. ---------- assignee: docs@python components: Documentation messages: 308497 nosy: Decorater, docs@python priority: normal severity: normal status: open title: Add docs about Embedding with an frozen module limitation. versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32353> _______________________________________

1 1

confusing sentence correction
by George Herson Dec. 16, 2017

Dec. 16, 2017

Dear Sir/Ms., Just a suggestion (that I think is a good one): From page 4. More Control Flow Tools — Python 3.6.4rc1 documentation simply remove sentence "When used with a loop, the else clause has more in common with the else clause of a try statement than it does that of if statements: a try statement’s else clause runs when no exception occurs, and a loop’s else clause runs when no break occurs." I think that sentence is unnecessary and needlessly misleading and confusing. When examined closely, what the documentation specifies is that the else actually works the same with while as it does with if (namely that the else block is not executed if the loop exits by break). best regards,George Herson

1 0

[issue32263] Template string docs refer to "normal %-based substitutions"
by Glenn Linderman Dec. 16, 2017

Dec. 16, 2017

New submission from Glenn Linderman <v+python(a)g.nevcal.com>: At least as far back as Python 3.1, the description for Template strings (section 6.1.5 in version 3.6.4rc1 docs) starts by differentiating what Template strings do, as: Instead of the normal %-based substitutions, Templates support $-based substitutions, using the following rules: Since this immediately follows a section describing the "Custom String Formatting" and the "Format Specification Mini-Language", which does a type of substitutions that is {} based, rather than % based, it is hard to grasp exactly why %-based substitutions would be considered "normal". Of course, I know why, due to the % operator, but for someone just reading through chapter 6, it is a reference that raises the mental question "Huh? What is normal %-based substitution? Are Templates abnormal, if %-based substitutions are normal? What did I miss? The previous section was about {}-based substitutions? Are they abnormal, too? What are normal %-based substitutions, anyway?" rather than helping to describe what Templates are and do. ---------- assignee: docs@python components: Documentation messages: 307922 nosy: docs@python, v+python priority: normal severity: normal status: open title: Template string docs refer to "normal %-based substitutions" versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32263> _______________________________________

4 6

[issue32341] itertools "generators"?
by Stefan Pochmann Dec. 15, 2017

Dec. 15, 2017

New submission from Stefan Pochmann <stefan.pochmann(a)gmail.com>: The itertools page https://docs.python.org/3.6/library/itertools.html says "Combinatoric generators:" above the table with product(), permutations(), etc. But as far as I understand, they're not generators and they don't produce generator iterators. I think the table title should be "Combinatoric iterators:" instead, in line with "Infinite Iterators:" and "Iterators terminating on the shortest input sequence:" of the two tables above it. Reference: https://docs.python.org/3/glossary.html#term-generator ---------- assignee: docs@python components: Documentation messages: 308425 nosy: Stefan Pochmann, docs@python priority: normal severity: normal status: open title: itertools "generators"? versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32341> _______________________________________

3 4

[issue32124] Document functions safe to be called before Py_Initialize()
by STINNER Victor Dec. 15, 2017

Dec. 15, 2017

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

f-strings
by Wagner Herculano Dec. 14, 2017

Dec. 14, 2017

Good evening, I'm Wagner Herculano from Brazil. I was trying to do a table exercise with number 5 and tried formatting spaces and did not find it in PEP 498 documentation. Finally I found a way, if possible, include this example in the documentation please. Below is my script with the desired formatting about table of 5. n = 5 for i in range(1,11): print(f'{n} x {i:>2} = {n*i:>2}') Result 5 x 1 = 5 5 x 2 = 10 5 x 3 = 15 5 x 4 = 20 5 x 5 = 25 5 x 6 = 30 5 x 7 = 35 5 x 8 = 40 5 x 9 = 45 5 x 10 = 50 ----------- Sorry my English, I needed to use Google Translate Best Regards, Wagner Herculano

1 0

windows help file .chm corrupted
by Michael Dec. 14, 2017

Dec. 14, 2017

Hi, there, The windows help file .chm is corrupted. No contents are available. https://www.python.org/ftp/python/3.6.4/python364rc1.chm -- Sincerely Yours, Michael Chen, Associate Professor Dept. Math & Stats, York Univ. Office: TEL 2034 tel.: 416-736-2100 ext. 66677

1 0