docs February 2012

docs@python.org

30 participants
340 discussions

[issue8595] Unexpected default timeout in http-client-related libraries

by Julian

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> _______________________________________

2 weeks, 5 days

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced

by anatoly techtonik

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> _______________________________________

2 weeks, 5 days

[issue13341] Incorrect documentation for "u" PyArg_Parse format unit

by Ilya Novoselov

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> _______________________________________

1 month, 2 weeks

[issue13875] cmd: no user documentation

by anatoly techtonik

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> _______________________________________

2 months

[issue9538] Replace confusing pseudoname 'object' in special methods section.

by Terry J. Reedy

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> _______________________________________

2 months

[issue13561] os.listdir documentation should mention surrogateescape

by Michael Foord

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> _______________________________________

2 months

[issue12594] Docs for py3k still refer to "MacPython 2.5 folder"

by Christoph Schindler

New submission from Christoph Schindler <hop(a)30hopsmax.at>: In http://docs.python.org/py3k/using/mac.html#getting-and-installing-macpython and http://docs.python.org/py3k/using/mac.html#distributing-python-applications… . ---------- assignee: docs@python components: Documentation messages: 140744 nosy: docs@python, hop priority: normal severity: normal status: open title: Docs for py3k still refer to "MacPython 2.5 folder" versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12594> _______________________________________

2 months

[issue10709] Misc/AIX-NOTES needs updating

by Antoine Pitrou

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> _______________________________________

2 months, 1 week

[issue10529] Write argparse i18n howto

by Éric Araujo

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> _______________________________________

2 months, 1 week

[issue14003] __self__ on built-in functions is not as documented

by Роман Донченко

New submission from Роман Донченко <DXDragon(a)yandex.ru>: The language reference says this in section 3.2: ~ Built-in functions A built-in function object is a wrapper around a C function. Examples of built-in functions are len() and math.sin() <...> Special read-only attributes: <...> __self__ is set to None (but see the next item) <...>. ~ That is not the case: ActivePython 3.2.2.3 (ActiveState Software Inc.) based on Python 3.2.2 (default, Sep 8 2011, 10:55:13) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> len.__self__ <module 'builtins' (built-in)> >>> open.__self__ <module 'io' (built-in)> >>> import math >>> math.sin.__self__ <module 'math' (built-in)> ---------- assignee: docs@python components: Documentation messages: 153287 nosy: SpecLad, docs@python priority: normal severity: normal status: open title: __self__ on built-in functions is not as documented type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14003> _______________________________________

2 months, 1 week

Jump to page:

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs February 2012