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>
_______________________________________
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>
_______________________________________
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>
_______________________________________
Stéphane Wirtel <stephane(a)wirtel.be> added the comment:
Hi Scoder,
I am not sure if this issue is relevant for 3.7 and 3.8 but do you want to check this issue?
Thank you,
----------
nosy: +matrixise, scoder
versions: +Python 3.7, Python 3.8 -Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue10108>
_______________________________________
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>
_______________________________________
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>
_______________________________________
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>
_______________________________________
New submission from wim glenn <wim.glenn(a)gmail.com>:
Section https://docs.python.org/3/library/collections.html#ordereddict-examples-and…
class LastUpdatedOrderedDict(OrderedDict):
'Store items in the order the keys were last added'
def __setitem__(self, key, value):
super().__setitem__(key, value)
super().move_to_end(key)
Why does it use super().move_to_end(key), isn't self.move_to_end(key) more direct/Pythonic?
----------
assignee: docs@python
components: Documentation
messages: 342395
nosy: docs@python, rhettinger, wim.glenn
priority: normal
pull_requests: 13209
severity: normal
status: open
title: LastUpdatedOrderedDict recipe uses super() unnecessarily
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue36909>
_______________________________________