Mailman 3 June 2011 - docs

[issue11975] Fix intersphinx-ing of built-in types (list, int, ...)
by Jonas H. April 28, 2021

April 28, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...). Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work. ---------- assignee: docs@python components: Documentation messages: 134923 nosy: docs@python, jonash priority: normal severity: normal status: open title: Fix intersphinx-ing of built-in types (list, int, ...) _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11975> _______________________________________

11 50

[issue11977] Document int.conjugate, .denominator, ...
by Jonas H. April 23, 2021

April 23, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them): * .conjugate * .denominator * .imag * .numerator * .real ---------- assignee: docs@python components: Documentation messages: 134926 nosy: docs@python, jonash priority: normal severity: normal status: open title: Document int.conjugate, .denominator, ... versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

6 8

[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

[issue9538] Replace confusing pseudoname 'object' in special methods section.
by Terry J. Reedy Nov. 17, 2020

Nov. 17, 2020

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

5 8

[issue10709] Misc/AIX-NOTES needs updating
by Antoine Pitrou Nov. 11, 2020

Nov. 11, 2020

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

5 14

[issue10529] Write argparse i18n howto
by Éric Araujo Nov. 7, 2020

Nov. 7, 2020

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

5 5

[issue11176] give more meaningful argument names in argparse documentation
by Steven Bethard Nov. 6, 2020

Nov. 6, 2020

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

13 23

[issue12436] Provide reference to detailed installation instructions
by Nick Coghlan Nov. 6, 2020

Nov. 6, 2020

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The Boston Python Workshop folks have some detailed step-by-step instructions on getting Python up and running ([1]). Given that this can be a pain point for new users (primarily on Windows), it may be good to reference these instructions from the official docs. (Alternatively, we could use them as the basis for a "HOWTO" in the official docs and update release.py to adjust the relevant links. That's a lot more work than just adding a link, though) [1] http://openhatch.org/wiki/Boston_Python_Workshop_3/Friday ---------- assignee: docs@python components: Documentation messages: 139381 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Provide reference to detailed installation instructions _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12436> _______________________________________

10 28