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 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 Antoine Pitrou <pitrou(a)free.fr>:
Sébastien, would you like to provide an updated version of that file? The current contents look hopelessly outdated.
----------
assignee: docs@python
components: Documentation
messages: 124024
nosy: docs@python, pitrou, sable
priority: normal
severity: normal
stage: needs patch
status: open
title: Misc/AIX-NOTES needs updating
versions: Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10709>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
argparse helpfully makes its messages with gettext.gettext. The docs should explain how to benefit from that in one’s program.
----------
assignee: docs@python
components: Documentation
messages: 122358
nosy: bethard, docs@python, eric.araujo
priority: normal
severity: normal
stage: needs patch
status: open
title: Write argparse i18n howto
type: feature request
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10529>
_______________________________________
New submission from Steven Bethard <steven.bethard(a)gmail.com>:
Suggestion from a personal email:
I personally am not keen on the foo/bar/baz examples. I
know that you're trying to be generic but IMO it would be much easier to
understand if you used meaningful names. Also, I think that the very
first example you give (which does use meaningful names:-) is too
clever. I'd suggest using something simpler: in fact I'd use exactly the
same example that optparse uses (--file && --quiet) since that is easy
to understand and relate to straight away, and maybe add a --line option
that takes a list of ints (ostensibly line numbers of lines to extract
from the file) if you want to show that argparse leaves optparse in the
dust. And you can always show how to get actual file objects later on.
----------
assignee: docs@python
components: Documentation
messages: 128302
nosy: bethard, docs@python
priority: normal
severity: normal
stage: needs patch
status: open
title: give more meaningful argument names in argparse documentation
type: feature request
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11176>
_______________________________________
New submission from Atsuo Ishimoto <ishimoto(a)gembook.org>:
In the gc.garbage of the library ref of gc module,
... this list contains only objects with __del__() methods.
This is not true, since gc.garbage will contain generator object with try-finally block.
----------
assignee: docs@python
components: Documentation
messages: 129631
nosy: docs@python, ishimoto
priority: normal
severity: normal
status: open
title: Generator object should be mentioned in gc module document
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11346>
_______________________________________
New submission from Campbell Barton <ideasman42(a)gmail.com>:
Some parts of the python api expect __main__ module dictionary to be the namespace when executing a script, this is true when running a python script from the python binary but NOT true when running a compiled script from the C/API which can lead to bugs which are not easy to solve unless the C/API author knows this.
----------
assignee: docs@python
components: Documentation
files: doc_py3_main_mod.diff
keywords: patch
messages: 112706
nosy: docs@python, ideasman42
priority: normal
severity: normal
status: open
title: Python C/API Execution namespace undocumented. (patch included)
type: behavior
versions: Python 3.2
Added file: http://bugs.python.org/file18357/doc_py3_main_mod.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9499>
_______________________________________
New submission from Christopher Dunn <cdunn2001(a)gmail.com>:
This is an easy one.
When I zoom my browser in (with Ctrl+ or Apple+) the left-side navigation margin gets bigger and bigger, pushing the useful text off the screen. That has bothered me (and anyone else with 40+ year old eyes) ever since the switch to the newest doc format with Sphinx.
There is no fix that will satisfy everyone. People with perfect vision might like to zoom out (with Ctrl- or Apple-), since the margin currently gets smaller and smaller. But we need a compromise.
The relevant CSS, in default.css, is this:
div.bodywrapper {
margin: 0 0 0 230px;
}
If instead it were something like this:
div.bodywrapper {
margin: 0 0 0 10%;
}
then at least the navigation margin would stay the same size always.
If you really want it to grow and shrink, then you need some sort of javascript control of its position.
----------
assignee: docs@python
components: Documentation
messages: 126477
nosy: cdunn2001, docs@python
priority: normal
severity: normal
status: open
title: Simple CSS fix for left margin at docs.python.org
type: behavior
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10936>
_______________________________________
New submission from Craig McQueen <python(a)craig.mcqueen.id.au>:
I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()".
Here is what I have found (I think), and it could be worth improving the documentation of this somehow.
Example 1:
"%s" % test_object
>From what I can tell, in this case:
1. test_object.__str__() is called.
2. If test_object.__str__() returns a string object, then that is substituted.
3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising.
[Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.]
Example 2:
u"%s" % test_object
In this case:
1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode.
2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode.
Example 3:
"%s %s" % (u'unicode', test_object)
In this case:
1. The first substitution causes the output string to be Unicode.
2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising.
----------
assignee: docs@python
components: Documentation
messages: 109516
nosy: cmcqueen1975, docs@python
priority: normal
severity: normal
status: open
title: Improve docs for string interpolation "%s" re Unicode strings
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9196>
_______________________________________