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 Guy Taylor <thebigguy.co.uk(a)gmail.com>:
The Python docs suggest that io.IOBase.truncate' should take a keyword argument of 'size'.
However this causes a 'TypeError':
TypeError: truncate() takes no keyword arguments
Suggest that the docs are changed to 'truncate(size)' or CPython is changed to allow the keyword.
http://docs.python.org/py3k/library/io.html?highlight=truncate#io.IOBase.tr…http://docs.python.org/library/io.html?highlight=truncate#io.IOBase.truncate
----------
assignee: docs@python
components: Documentation, Interpreter Core
files: test.py
messages: 158308
nosy: TheBiggerGuy, docs@python
priority: normal
severity: normal
status: open
title: TypeError: truncate() takes no keyword arguments
type: behavior
versions: Python 2.7, Python 3.2
Added file: http://bugs.python.org/file25219/test.py
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue14586>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
http://docs.python.org/library/__main__.html
"It is this environment in which the idiomatic “conditional script” stanza causes a script to run"
?!?
----------
assignee: docs@python
components: Documentation
messages: 163140
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: abusive language in __name__ description
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue15104>
_______________________________________
New submission from Ilya Novoselov <ilya.novoselov(a)gmail.com>:
Documentation states that u format unit returns "buffer of 16-bit Unicode (UTF-16) data" while it returns pointer to internal buffer of unicode data, which is either UCS-16 or UCS-32
http://docs.python.org/c-api/arg.html
----------
assignee: docs@python
components: Documentation, Unicode
messages: 147002
nosy: Ilya.Novoselov, docs@python, ezio.melotti
priority: normal
severity: normal
status: open
title: Incorrect documentation for "u" PyArg_Parse format unit
type: behavior
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
http://docs.python.org/library/cmd.html#
Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing?
So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info.
At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/
----------
assignee: docs@python
components: Documentation
messages: 152010
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: cmd: no user documentation
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13875>
_______________________________________
New submission from Terry J. Reedy <tjreedy(a)udel.edu>:
In 3.3. Special method names, 'object' is used as a pseudo class name to prefix all the special method entries. This conflicts with the usual two Python meanings.
1. 'object' is the name of a specific class. So the entry for object.__getattribute__(self, name) says to avoid circularity by calling
object.__getattribute__(self, name), which looks circular and requires a bit a mental work by the reader to properly understand. Ditto for
object.__setattr__(self, name, value) calling
object.__setattr__(self, name, value)
2. Non-specifically, 'object' is usually understood to mean any Python object, not just a class. But the signatures as written require that 'object' specifically be a class and 'object' does not convey that.
So for both reasons, I propose that the pseudoname 'object' be replaces with 'class' or 'someclass'
----------
assignee: docs@python
components: Documentation
messages: 113194
nosy: docs@python, georg.brandl, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Replace confusing pseudoname 'object' in special methods section.
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9538>
_______________________________________
New submission from Michael Foord <michael(a)voidspace.org.uk>:
Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example).
This should be documented.
----------
assignee: docs@python
components: Documentation
messages: 149070
nosy: docs@python, michael.foord
priority: normal
severity: normal
stage: needs patch
status: open
title: os.listdir documentation should mention surrogateescape
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13561>
_______________________________________