Mailman 3 May 2010 - docs

[issue8557] subprocess portability issue
by Dave Abrahams March 5, 2021

March 5, 2021

New submission from Dave Abrahams <dave(a)boostpro.com>: On POSIX systems, the PATH environment variable is always used to look up directory-less executable names passed as the first argument to Popen(...), but on Windows, PATH is only considered when shell=True is also passed. Actually I think it may be slightly weirder than that when shell=False, because the following holds for me: C:\>rem ##### Prepare minimal PATH ##### C:\>set "PATH=C:\Python26\Scripts;C:\Python26;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem" C:\>rem ##### Prepare a minimal, clean environment ##### C:\>virtualenv --no-site-packages e:\zzz New python executable in e:\zzz\Scripts\python.exe Installing setuptools................done. C:\>rem ##### Show that shell=True makes the difference in determining whether PATH is respected ##### C:\>python Python 2.6.5 (r265:79096, Mar 19 2010, 18:02:59) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import subprocess >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable']) <subprocess.Popen object at 0x0000000001DBE080> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}) <subprocess.Popen object at 0x0000000001F05A90> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}, shell=True) <subprocess.Popen object at 0x0000000001F05B00> >>> e:\zzz\Scripts\python.exe That is, it looks like the environment at the time Python is invoked is what counts unless I pass shell=True. I don't even seem to be able to override this behavior by changing os.environ: you can clear() it and pass env={} and subprocess.Popen(['python']) still succeeds. This is a very important problem for portable code and one that took me hours to suss out. I think: a) the current behavior needs to be documented b) it needs to be fixed if possible c) otherwise, shell=True should be the default ---------- assignee: docs@python components: Documentation messages: 104422 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: subprocess portability issue type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8557> _______________________________________

8 23

[issue8595] Unexpected default timeout in http-client-related libraries
by Julian Dec. 29, 2020

Dec. 29, 2020

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

5 8

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
by anatoly techtonik Dec. 29, 2020

Dec. 29, 2020

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

6 15

[issue8824] Improve documentation of exec
by Terry J. Reedy Feb. 28, 2020

Feb. 28, 2020

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread 'variable name resolution in exec is incorrect' (which is not a correct claim). I believe there is consensus that the doc for exec needs improving. My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry) "In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary, which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object." have these two sentences added: "If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope." ---------- assignee: docs@python components: Documentation messages: 106552 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Improve documentation of exec versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8824> _______________________________________

6 19

[issue8722] Documentation for __getattr__
by Paul Davis Feb. 5, 2018

Feb. 5, 2018

New submission from Paul Davis <paul.joseph.davis(a)gmail.com>: The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated. The attached script demonstrates the issue on OS X 10.6, Python 2.6.1 I'm thinking something along the lines of: If the attribute search encounters an AttributeError (perhaps due to a @property raising the error) the search is considered a failure and __getattr__ is invoked. ---------- assignee: docs@python components: Documentation files: example.py messages: 105790 nosy: Paul.Davis, docs@python priority: normal severity: normal status: open title: Documentation for __getattr__ type: feature request versions: Python 2.6 Added file: http://bugs.python.org/file17349/example.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8722> _______________________________________

8 23

[issue8810] TZ offset description is unclear in docs
by Alexander Belopolsky Feb. 8, 2016

Feb. 8, 2016

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: >From <http://docs.python.org/dev/py3k/library/datetime.html#datetime.tzinfo.utcof…>: """ tzinfo.utcoffset(self, dt) Return offset of local time from UTC, in minutes east of UTC. """ This suggests that the return value is an integer representing the number of minutes. It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence. I suggest s/in minutes east of UTC/as a timedelta object/. I think "east of UTC" is redundant given the next sentence, "If local time is west of UTC, this should be negative", but that can also be reworded for clarity as "The offset for timezones west of UTC is negative, and for those east of UTC is positive." ---------- assignee: docs@python components: Documentation keywords: easy messages: 106371 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: TZ offset description is unclear in docs versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8810> _______________________________________

6 19

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial
by Marien Zwart June 8, 2012

June 8, 2012

New submission from Marien Zwart <m_zwart(a)123mail.org>: Based on questions asked on freenode's #python by people reading the tutorial I would like to suggest two improvements to http://docs.python.org/tutorial/errors.html#handling-exceptions : - Mention the older "except SomeException, e:" syntax too, not just "except SomeException as e:". I have had people ask me to help them upgrade to a newer python because they thought their version of python did not support catching exception instances (their distro python being 2.5). A big fat warning that they're reading the Python 2.6 tutorial (with links to older tutorials) may also work. - Mention "except IOError as e" before mentioning "except IOError as (errno, strerror):". The latter is an advanced and relatively unusual trick, combining regular exception catching and unpacking. Those two concepts need to be explained before the combination is. I have had people ask me how to do "except KeyError as (key, insert_something_here):" because they thought they *always* needed those parens there. (perhaps just not mentioning unpacking here at all, using "except IOError as e:" and then using e.errno would make more sense, especially since "except IOError as (errno, strerror):" is a SyntaxError in python 3 and up (because of the unpacking) and python 2.5.x and down (because of the "as")...) I can try to write a patch to the documentation if you like. ---------- assignee: docs@python components: Documentation messages: 105218 nosy: docs@python, marienz priority: normal severity: normal status: open title: Minor improvements to the "Handling Exceptions" part of the tutorial _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8652> _______________________________________

4 6

[issue8617] Non-existent variables documented
by Dave Abrahams May 9, 2012

May 9, 2012

New submission from Dave Abrahams <dave(a)boostpro.com>: http://docs.python.org/library/site.html#module-site mentions two variables that don't appear in my Python 2.6.5 installation's site module: PYTHONNOUSERSITE New in version 2.6. PYTHONUSERBASE New in version 2.6. ---------- assignee: docs@python components: Documentation messages: 104985 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: Non-existent variables documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8617> _______________________________________

6 13

[issue8646] PyUnicode_EncodeDecimal is undocumented
by Daniel Stutzbach Nov. 22, 2011

Nov. 22, 2011

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: PyUnicode_EncodeDecimal is undocumented (although it's referenced in passing in the documentation for PyLong_FromUnicode). There's a lengthy comment in unicodeobject.h describing PyUnicode_EncodeDecimal, which could be converted more or less directly into documentation. ---------- assignee: docs@python components: Documentation messages: 105205 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: PyUnicode_EncodeDecimal is undocumented versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8646> _______________________________________

4 6

[issue8691] Doc: left alignment is not the default for numbers
by Terry J. Reedy Feb. 7, 2011

Feb. 7, 2011

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: As reported on python-list by Alan G Isaac, Lib Ref 6.1.3.1. Format Specification Mini-Language, for instance http://docs.python.org/dev/py3k/library/string.html#formatstrings wrongly says in the alignment section "'<' Forces the field to be left-aligned within the available space (This is the default.)" This latter, of course, is not true for number fields. "(This is the default.)" could be replaced by "(the string default)." (in any case, the '.' should be outside the () unless one is added after 'space' before '(') and "(the number default)" added to the next line. Or instead the issue of defaults could be addressed in the text below the table. I am assuming that this issue affects 2.6/7. ---------- assignee: docs@python components: Documentation messages: 105536 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Doc: left alignment is not the default for numbers versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8691> _______________________________________

4 5