New submission from swanson:
https://docs.python.org/3/reference/expressions.html
in
6.2.9. Yield expressions
end of 1st paragraph:
"Using a yield expression in a function’s body causes that function to be a generator."
NO!
As the very next sentence explains, a generator is what's returned by such a function, not the function itself.
Basically, it should be sufficient to add the word "function" to the end of that sentence: "... generator function." However, this error does NOT exist in 3.0 to 3.2 - just in 3.3 to 3.6, so I suggest just using the same wording as 3.0 to 3.2:
"Using a yield expression in a function definition is sufficient to cause that definition to create a generator function instead of a normal function."
----------
assignee: docs@python
components: Documentation
messages: 246841
nosy: docs@python, swanson
priority: normal
severity: normal
status: open
title: Error in yield expression documentation
versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue24650>
_______________________________________
New submission from Markus Unterwaditzer:
getpass.getpass doesn't enter a newline when the user aborts input with ^C, while input/raw_input does.
This behavior is surprising and can lead to mis-formatting of subsequent output. However, since this behavior exists since 2.7 and applications may have started to rely on it, I'd add a note to the documentation.
----------
assignee: docs@python
components: Documentation
messages: 247302
nosy: docs@python, untitaker
priority: normal
severity: normal
status: open
title: Document getpass.getpass behavior on ^C
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue24711>
_______________________________________
New submission from Aydin <bagiyevaydin(a)gmail.com>:
In the documentation of Python 3.7.0 there is an error in the usage of the world 'for example'.
----------
assignee: docs@python
components: Documentation
files: Functional Programming HOWTO — Python 3.7.0 documentation.png
messages: 326418
nosy: docs@python, rarblack
priority: normal
severity: normal
status: open
title: Repetition of 'for example' in documentation
versions: Python 3.7
Added file: https://bugs.python.org/file47825/Functional Programming HOWTO — Python 3.7.0 documentation.png
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue34804>
_______________________________________
New submission from Jonathan Fine <jfine2358(a)gmail.com>:
Interactive code examples need the prompt to be stripped, before copy-and-paste. This is explained in https://docs.python.org/3/tutorial/introduction.html
But this page does not tell us about the [>>>] prompt-toggle at top of each interactive code example. This caused a user error, reported in https://mail.python.org/pipermail/python-ideas/2018-August/052869.html.
The [>>>] toggle isn't in the Python 2.7 docs, so nothing to fix there!
----------
assignee: docs@python
components: Documentation
messages: 323839
nosy: docs@python, jfine2358
priority: normal
severity: normal
status: open
title: docs: tutorial/introduction doesn't mention toggle of prompts
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/issue34451>
_______________________________________
New submission from Merlijn van Deen <valhallasw(a)gmail.com>:
http://docs.python.org/library/threading.html#importing-in-threaded-code
Currently, the documentation states
"Firstly, other than in the main module, an import should not have the side effect of spawning a new thread and then waiting for that thread in any way. Failing to abide by this restriction can lead to a deadlock if the spawned thread directly or indirectly attempts to import a module."
which, I think, fails to make the main point: a call to import acquires the import lock. A call to import from a second thread will thus block.
As such, I would suggest rephrasing it to something like:
"Firstly, an import acquires the import lock for that thread. Therefore, the import should not have the side effect of waiting for a different thread in any way, as this can lead to a deadlock if that thread directly or indirectly attempts to import a module."
There are two additional points that might be interesting to note:
(1) Any module can be imported. If the import causes a deadlock, that is a bad thing. Every module *will* be imported by tools such as nosetests.
(1b) so: never, ever, have code that causes locks in a different thread in module level code witout 'if __name__=="__main__" ' blocks?
(2) The lock is also acquired if a module has already been imported. For instance, in
import sys # (1)
def f():
import sys # (2)
the import lock is acquired in (1) /and/ (2).
Adding example code and/or a flow diagram might be a bit too much, but it does clarify how easy it is to make this mistake. See the attached for an example (both a simple example script, as well as a flow diagram explaining what happens).
----------
assignee: docs@python
components: Documentation
files: deadlock.py
messages: 163068
nosy: docs@python, valhallasw
priority: normal
severity: normal
status: open
title: Improving wording on the thread-safeness of import
type: enhancement
Added file: http://bugs.python.org/file26037/deadlock.py
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue15097>
_______________________________________
New submission from Julian <python_org(a)somethinkodd.com>:
Since Python 2.6, httplib has offered a timeout parameter for fetches. As the documentation explains, if this parameter is not provided, it uses the global default.
What the document doesn't explain is httplib builds on top of the socket library. The socket library has a default timeout of None (i.e. forever). This may be an appropriate default for general sockets, but it is a poor default for httplib; typical http clients would use a timeout in the 2-10 second range.
This problem is propagated up to urllib2, which sits on httplib, and further obscures that the default might be unsuitable.
>From an inspection of the manuals, Python 3.0.1 suffers from the same problem except, the names have changed. urllib.response sits on http.client.
I, for one, made a brutal mistake of assuming that the "global default" would be some reasonable default for fetching web pages; I didn't have any specific timeout in mind, and was happy for the library to take care of it. Several million successful http downloads later, my server application thread froze waiting forever when talking to a recalcitrant web-server. I imagine others have fallen for the same trap.
While an ideal solution would be for httplib and http.client to use a more generally acceptable default, I can see it might be far too late to make such a change without breaking existing applications. Failing that, I would recommend that the documentation for httplib, urllib, urllib2, http.client and urllib.request (+ any other similar libraries sitting on socket? FTP, SMTP?) be changed to highlight that the default global timeout, sans deliberate override, is to wait a surprisingly long time.
----------
assignee: docs@python
components: Documentation, Library (Lib)
messages: 104763
nosy: docs@python, oddthinking
priority: normal
severity: normal
status: open
title: Unexpected default timeout in http-client-related libraries
type: behavior
versions: Python 2.6, Python 2.7, Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8595>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation.
----------
assignee: docs@python
components: Documentation
messages: 106524
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: datetime naive and aware types should have a well-defined definition that can be cross-referenced
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8822>
_______________________________________
New submission from Vladislavs Burakovs <solomonchild(a)gmail.com>:
Documentation page [1] says "If the object has a method named __dir__(), this method will be called and must return the list of attributes.".
It seems that on Python 3.6 it only works if the *class* has a method named __dir__. Should the documentation be changed?
Microsoft Windows [Version 10.0.16299.192]
(c) 2017 Microsoft Corporation. All rights reserved.
D:\Users\wlad>python
Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> class C: pass
...
>>> x = C()
>>> import types
>>> x.__dir__ = types.MethodType(lambda _:[], x)
>>> dir(x)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__']
>>> C.__dir__ = types.MethodType(lambda _:[], x)
>>> dir(x)
[]
[1] https://docs.python.org/3/library/functions.html
----------
assignee: docs@python
components: Documentation
messages: 309544
nosy: Vladislavs Burakovs, docs@python
priority: normal
severity: normal
status: open
title: Documentation for dir([object])
type: enhancement
versions: Python 3.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue32501>
_______________________________________
New submission from Jake:
In the statistics module documentation, there is a note that states that
"The mean is strongly affected by outliers and is not a robust estimator for central location: the mean is not necessarily a typical example of the data points. For more robust, although less efficient, measures of central location, see median() and mode()"
https://docs.python.org/3/library/statistics.html
While I appreciate the intention, this is quite misleading. The implication is that the mean, median and mode are different ways to estimate one "central location", however, in reality they are very different things (albeit which refer to a similar notion).
The sample mean is an unbiased estimator of the true mean but it need not be unbiased as an estimator of the true median or modes and vice versa for the median and mode.
To make this clearer I would rephrase to
"The mean is strongly affected by outliers and is not necessarily representative of the central tendency of the data. For cases with large outliers or very low sample size, see median() and mode()"
Apologies if this is seen as frivolous, but statistics can be hard enough to remain very clear about even when the words are used precisely.
----------
assignee: docs@python
components: Documentation
messages: 236612
nosy: Journeyman08, docs@python
priority: normal
severity: normal
status: open
title: Misleading note in Statistics module documentation
type: enhancement
versions: Python 3.4
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue23522>
_______________________________________
New submission from Jonathan Fine <jfine2358(a)gmail.com>:
The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary.
Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry
===
iterable
An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any [...]
===
#788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial.
I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation."
----------
assignee: docs@python
components: Documentation
messages: 323503
nosy: docs@python, jfine2358
priority: normal
severity: normal
status: open
title: Docs search does not index glossary
type: behavior
versions: Python 2.7, 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/issue34398>
_______________________________________