Mailman 3 April 2019 - docs

[issue19175] Erroneous reference to "integer" in format string grammar
by David Chambers 17 May '19

17 May '19

New submission from David Chambers: I first raised this issue on Stack Overflow: http://stackoverflow.com/questions/19203194 The [replacement field grammar][1] states that an [integer][2] is a valid field_name, but this is inaccurate: >>> '{0}'.format('zero') 'zero' >>> '{0x0}.format('zero') KeyError: '0x0' >>> '{0o0}.format('zero') KeyError: '0o0' >>> '{0b0}.format('zero') KeyError: '0b0' This [comment][3] by Eric Smith suggests that the above is the intended behaviour: > get_integer uses the narrowest possible definition for integer indexes, > in order to pass all other strings to mappings. The documentation should be updated to match the actual behaviour. abarnert on Stack Overflow suggested the following change: -arg_name ::= [identifier | integer] +arg_name ::= [identifier | digit+] [1]: http://docs.python.org/2/library/string.html#format-string-syntax [2]: http://docs.python.org/2/reference/lexical_analysis.html#grammar-token-inte… [3]: http://bugs.python.org/issue8985#msg107705 ---------- assignee: docs@python components: Documentation messages: 199024 nosy: davidchambers, docs@python priority: normal severity: normal status: open title: Erroneous reference to "integer" in format string grammar 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/issue19175> _______________________________________

3 3

[issue34648] Confirm the type of traceback.format_list post-3.5
by Nathaniel Manista 15 May '19

15 May '19

New submission from Nathaniel Manista <nathaniel(a)google.com>: So I'm fixing a bug in typeshed's accounting of the traceback module (https://github.com/python/typeshed/pull/2436) and the documented semantics of traceback.format_list don't quite smell to me what I think they might be intended to be: 1) I know it has the name "format_list", but is it really intended to require a list? Why not a sequence, or a collection, or an iterable? I would think it would be fine to pass an iterable to traceback.format_list. Is it fine? 2) What is the desired component type for the aggregate passed to format_list? In 3.4-and-earlier it was Tuple[str, int, str, Optional[str]], and that still works in 3.5-through-3.8, but is that just backwards compatibility or is that something that users of traceback.format_list should feel encouraged to continue passing into the future? Sorry for filing a bug just to ask "huh; really?" but... please confirm? ---------- assignee: docs@python components: Documentation messages: 325175 nosy: Nathaniel Manista, docs@python priority: normal severity: normal status: open title: Confirm the type of traceback.format_list post-3.5 type: behavior versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34648> _______________________________________

5 8

[issue34682] Typo reports on docs@
by Zachary Ware 15 May '19

15 May '19

New submission from Zachary Ware <zachary.ware(a)gmail.com>: >From ZooDSS (Никита Люшненко) on docs@: https://mail.python.org/pipermail/docs/2018-September/037223.html : """ https://docs.python.org/3/reference/datamodel.html#metaclass-example - "uses an collections.OrderedDict to remember" when it is better to use "uses a collections.OrderedDict to remember" https://docs.python.org/3/reference/executionmodel.html#exceptions "Exceptions are a means" - Is it correct to use "a" here? "means" means a lot of them. "a" means one. "In either case, it prints a stack backtrace" - most of the time in Python documentation term "traceback" is used instead of "backtrace". It may mislead newcomers, so they will think, that this is potentially a new term. https://docs.python.org/3/reference/expressions.html#yield-expressions "Due to their side effects on the containing scope, yield expressions are not permitted as part of the implicitly defined scopes used to implement comprehensions and generator expressions (in Python 3.7, such expressions emit DeprecationWarning when compiled, in Python 3.8+ they will emit SyntaxError).." - two periods in the end of the sentence. https://docs.python.org/3/reference/expressions.html#yield-expressions "...or automatically when the sub-iterator is a generator (by returning a value from the sub-generator)." - inconsistent use of "sub-iterator" term. Previously subiterator was referenced several times as "subiterator" not "sub-iterator". If i understood something wrong, then i am sorry. """ https://mail.python.org/pipermail/docs/2018-September/037224.html : """ https://docs.python.org/3/reference/expressions.html#yield-expressions Term "sub-generator" is used in PEP 280 without dash ("-") symbol - "subgenerator". At the same time it is used as "sub-generator" 2 times on this page: "generator (by returning a value from the sub-generator)." - here. "The proposal to introduce the yield_from syntax, making delegation to sub-generators easy." - and here. """ https://mail.python.org/pipermail/docs/2018-September/037237.html : """ https://docs.python.org/3/reference/expressions.html#asynchronous-generator… "function as a asynchronous generator function." - it's better to say "function as an asynchronous generator function." https://docs.python.org/3/reference/expressions.html#agen.__anext__ "When an asynchronous generator function is resumed with a __anext__() method" - may be better "...function is resumed with an __anext__() method". "the awaitable instead raises an StopAsyncIteration exception" - at the same time here may be better to use "the awaitable instead raises a StopAsyncIteration exception". https://docs.python.org/3/reference/expressions.html#agen.athrow "an StopAsyncIteration exception is raised" - here is the same situation as previously. "a" instead of "an" may be better. Here goes very special case, and if i am wrong you can laugh on me as much as you wish! =) https://docs.python.org/3/reference/expressions.html#parenthesized-forms "Since tuples are immutable, the rules for literals apply" - Tuples are immutable, but not literals. So may be "the same rules as for literals apply" is better? Or does it apply exactly those rules, that apply for literals? "()" - this is a literal, that yelds an empty tuple. But this doesn't connect, or i am wrong? If i am - then i am very sorry. Again, if i mistook something - i am sorry. Thanks for the good work. This is the best documentation i've ever seen. """ ---------- assignee: docs@python components: Documentation messages: 325362 nosy: docs@python, zach.ware priority: normal severity: normal stage: needs patch status: open title: Typo reports on docs@ versions: Python 2.7, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34682> _______________________________________

9 12

[issue36345] Deprecate Tools/scripts/serve.py in favour of python -m http.server -d
by Stéphane Wirtel 15 May '19

15 May '19

New submission from Stéphane Wirtel <stephane(a)wirtel.be>: The Makefile of Doc/ has a `serve` target. Currently, this one uses `Tools/scripts/serve.py`. But since 3.7, this script could be replaced by `python -m http.server -d directory`. @mdk and myself thinking we could deprecate `Tools/scripts/serve.py` with a warning and propose to use `-m http.server -d directory` ---------- assignee: docs@python components: Documentation messages: 338224 nosy: docs@python, matrixise priority: normal severity: normal status: open title: Deprecate Tools/scripts/serve.py in favour of python -m http.server -d versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36345> _______________________________________

7 29

[issue21202] Naming a file` io.py` causes cryptic error message
by Madison May 15 May '19

15 May '19

New submission from Madison May: Naming a file `io.py` in the root directory of a project causes the following error on 2.7: AttributeError: 'module' object has no attribute 'BufferedIOBase' Similar issues arise on 3.x., although the error message is a bit more useful: Fatal Python error: Py_Initialize: can't initialize sys standard streams AttributeError: 'module' object has no attribute 'OpenWrapper' At the very least we should ensure that the error message is a bit more straightforward and clear, as I imagine its not all that uncommon to cause this kind of conflict. ---------- assignee: docs@python components: Documentation, IO messages: 215940 nosy: docs@python, madison.may priority: normal severity: normal status: open title: Naming a file` io.py` causes cryptic error message versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21202> _______________________________________

9 13

[issue34484] Unicode HOWTO incorrectly refers to Private Use Area for surrogateescape
by Mark Dickinson 14 May '19

14 May '19

New submission from Mark Dickinson <dickinsm(a)gmail.com>: The Unicode HOWTO currently has contains this text in the "Files in an Unknown Encoding" section [1]: > The surrogateescape error handler will decode any non-ASCII bytes as code > points in the Unicode Private Use Area ranging from U+DC80 to U+DCFF. These > private code points will then be turned back into the same bytes when the > surrogateescape error handler is used when encoding the data and writing it > back out. Unless I'm missing something, the subrange U+DC80 to U+DCFF of the low surrogates is *not* a Private Use Area. There *is* a kinda-sorta PUA in the high surrogates from U+DB80 to U+DBFF (because the only valid codepoints that use these surrogates in their UTF-16 encoding are the codepoints in planes 15 and 16, which are almost entirely PUA codepoints), but that's not what the surrogateescape handler is using. [1] https://docs.python.org/3/howto/unicode.html#files-in-an-unknown-encoding ---------- assignee: docs@python components: Documentation messages: 323976 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: Unicode HOWTO incorrectly refers to Private Use Area for surrogateescape versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34484> _______________________________________

3 9

[issue18478] Class bodies: when does a name become local?
by Terry J. Reedy 14 May '19

14 May '19

New submission from Terry J. Reedy: http://docs.python.org/3/reference/executionmodel.html#naming-and-binding says "The following are blocks: ... a class definition." and "If a name binding operation occurs anywhere within a code block, all uses of the name within the block are treated as references to the current block. This can lead to errors when a name is used within a block before it is bound. ..." This is definitely true for functions, but not for classes: foo = 'bar' class C: foo = foo print(C().foo) # bar This is the same for 3.3 and 2.7 with and without '(object)' added. Unless the code is considered to be buggy (probably since forever), the doc should be modified to change 'code block' to 'function code block' or maybe 'module or function code block'. (At near as I can think, the statement is true for modules, but only because globals() == locals(), so that part of the issue does not arise.) ---------- assignee: docs@python components: Documentation messages: 193205 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Class bodies: when does a name become local? type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18478> _______________________________________

5 11

[issue32995] Add a glossary entry for context variables
by Serhiy Storchaka 14 May '19

14 May '19

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: I think the term context variable is worth adding into the glossary. ---------- assignee: docs@python components: Documentation messages: 313241 nosy: docs@python, serhiy.storchaka, yselivanov priority: normal severity: normal status: open title: Add a glossary entry for context variables type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32995> _______________________________________

5 7

[issue30535] Warn that meta_path is not empty
by Xavier Morel 14 May '19

14 May '19

New submission from Xavier Morel: Encountered this issue porting Python 2 code manipulating meta_path to Python 3. In Python 2, meta_path is empty by default and its documentation specifically notes that: > sys.meta_path is searched before any implicit default finders or sys.path. As a result, sys.meta_path.append() works perfectly well and is overwhelmingly common[0]. In Python 3, this note was removed but the documentation does not specifically state default finders are present in meta_path, and the old code using sys.meta_path.append may now break as the default finders will silently take precedence on the custom ones if they believe they can do the job. I'd like to add a warning to the Python 3 documentation (3.5+?) noting the presence of existing default loaders, and to the Python 2 documentation suggesting `sys.meta_path.insert(0, finder)` for future-proofing, would there be objections or issues? [0] https://github.com/search?q=meta_path.append&type=Code&utf8=✓ ---------- assignee: docs@python components: Documentation messages: 294919 nosy: docs@python, xmorel priority: normal severity: normal status: open title: Warn that meta_path is not empty type: behavior versions: Python 2.7, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30535> _______________________________________

6 13

[issue35138] timeit documentation should have example with function arguments
by davidak 13 May '19

13 May '19

New submission from davidak <bugs.python.org+xdnb(a)davidak.de>: It is described here: https://www.pythoncentral.io/time-a-python-function/ I have just tested it. Works as expected. Best would be if timeit supports this natively. ---------- assignee: docs@python components: Documentation messages: 329079 nosy: davidak, docs@python priority: normal severity: normal status: open title: timeit documentation should have example with function arguments versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35138> _______________________________________

5 7