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:\… [View More]

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 … [View More]

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 … [View More]

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 … [View More]

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 … [View More]

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 … [View More]

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 … [View More]

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 … [View More]

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: … [View More]

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)… [View More]

4 5

[issue8648] The UTF-7 codec functions are undocumented
by Daniel Stutzbach Dec. 26, 2010

Dec. 26, 2010

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: The UTF-7 codec functions are undocumented: PyUnicode_DecodeUTF7Stateful PyUnicode_DecodeUTF7 PyUnicode_EncodeUTF7 ---------- assignee: docs@python components: Documentation messages: 105207 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: The UTF-7 codec functions are undocumented versions: Python 2.6, Python 3.1 _______________________________________ Python … [View More]

4 4

[issue8851] pkgutil document needs more markups
by MATSUI Tetsushi Dec. 15, 2010

Dec. 15, 2010

New submission from MATSUI Tetsushi <mft(a)users.sourceforge.net>: The library reference of pkgutil is only sparsely marked up. The attached patch is against 2.6 version, because I'm currently working with 2.6. Since a part of markups (namely :pep:'s) has already been done for 3.2 version, the patch cannot be applied directly to that version, and I haven't checked the versions in between. ---------- assignee: docs@python components: Documentation files: pkgutil.diff keywords: patch … [View More]

2 3

[issue8647] PyUnicode_GetMax is undocumented
by Daniel Stutzbach Nov. 20, 2010

Nov. 20, 2010

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: Here's the relevant signature: /* Get the maximum ordinal for a Unicode character. */ PyAPI_FUNC(Py_UNICODE) PyUnicode_GetMax(void); ---------- assignee: docs@python components: Documentation messages: 105206 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: PyUnicode_GetMax is undocumented versions: Python 2.7, Python 3.2 … [View More]

5 6

[issue8645] PyUnicode_AsEncodedObject is undocumented
by Daniel Stutzbach Nov. 20, 2010

Nov. 20, 2010

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: PyUnicode_AsEncodedObject is undocumented. It has the same signature as PyUnicode_AsEncodedString, although they do slightly different things based on a brief source code inspection (I'm not clear on what that difference is though). ---------- assignee: docs@python components: Documentation messages: 105203 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: … [View More]

4 5

[issue8649] Py_UNICODE_* functions are undocumented
by Daniel Stutzbach Nov. 16, 2010

Nov. 16, 2010

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: Python provides several functions for manipulating raw Py_UNICODE strings, but they aren't documented. Below are their signatures. PyAPI_FUNC(size_t) Py_UNICODE_strlen(const Py_UNICODE *u); PyAPI_FUNC(Py_UNICODE*) Py_UNICODE_strcpy( Py_UNICODE *s1, const Py_UNICODE *s2); PyAPI_FUNC(Py_UNICODE*) Py_UNICODE_strncpy( Py_UNICODE *s1, const Py_UNICODE *s2, size_t n); PyAPI_FUNC(int) Py_UNICODE_strcmp( … [View More]

5 5

[issue8855] Shelve documentation lacks security warning
by Longpoke Oct. 17, 2010

Oct. 17, 2010

New submission from Longpoke <longpoke(a)gmail.com>: Loading a shelve can cause arbitrary code to be executed [1] and other black magic (because it's backed by Pickle). Shouldn't there be a big fat warning at the top of the shelve documentation page? Unless you're like me and assume anything to do with serialization in any language is insecure until proved otherwise, you aren't going to intuitively think there is anything wrong with "unshelving" untrusted data (unless you already know … [View More]

3 3

[issue8811] fixing sqlite3 docs for py3k
by Shashwat Anand Oct. 17, 2010

Oct. 17, 2010

New submission from Shashwat Anand <anand.shashwat(a)gmail.com>: The docs of sqlite3 for python 3.0 and 3.1 seems to be written for python 2.6 and hence wrong at many places. like, >>> for member in r: print member However the docs for sqlite3 in py3k trunk seems fine. The sqlite3 doc in py3k trunk should be used in these places. http://docs.python.org/release/3.0.1/library/sqlite3.html http://docs.python.org/release/3.1/library/sqlite3.html ---------- assignee: docs@… [View More]

3 6

[issue8686] "This isn't defined beyond that" phrase is not friendly to non-native English speakers.
by INADA Naoki Oct. 17, 2010

Oct. 17, 2010

New submission from INADA Naoki <songofacandy(a)gmail.com>: http://docs.python.org/library/difflib.html#difflib.SequenceMatcher.quick_r… > This isn’t defined beyond that it is an upper bound on ratio(), and is faster to compute. "beyond" is a bit confusing because it also means "over" and this sentence refers upper bound. I think "This isn't defined in detail more than..." is easier. ---------- assignee: docs@python components: Documentation messages: 105498 nosy: docs@python, … [View More]

7 8

[issue8556] Confusing string formatting examples
by Jeff McNeil Oct. 17, 2010

Oct. 17, 2010

New submission from Jeff McNeil <jeff(a)jmcneil.net>: I was going through the string formatting examples this evening and noticed this: print '%(language)s has %(#)03d quote types.' % \ {'language': "Python", "#": 2} The example uses a '#' as a map key. This is somewhat misleading as if we had simply left the parenthesis off, the '#' would have been interpreted as an alternate conversion flag. Should be updated to use a more verbose (and less confusing) dictionary key. -----… [View More]

4 5

[issue8834] Define order of Misc/ACKS entries
by Alexander Belopolsky Aug. 10, 2010

Aug. 10, 2010

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: This is a semi-serious feature request following a brief discussion on #python-dev IRC. Brett Cannon pointed out on python-checkins list [1] that the names should be alphabetized. However, given that the names are international, it is not obvious what it means. I propose to add a comment at the top of Misc/ACKS that the list is maintained in "rough alphabetical order" but not define it any further. [1] … [View More]

6 10

[issue8562] hasattr(open, 'newlines') example gives incorrect results from PEP0278
by AdamN Aug. 2, 2010

Aug. 2, 2010

New submission from AdamN <adam(a)varud.com>: This bug from the Ubuntu list is being moved here: https://bugs.launchpad.net/ubuntu/+source/python-defaults/+bug/570737 Newlines support is enabled on Ubuntu but the example from: http://www.python.org/dev/peps/pep-0278/ Does not give the correct results (of True): if hasattr(open, 'newlines'): print 'We have universal newline support' I don't know if this is a documentation problem or whether there is another attr that … [View More]

4 3

[issue8602] documentation of bz2 module mildly erroneous
by Matt Wartell Aug. 1, 2010

Aug. 1, 2010

New submission from Matt Wartell <matt.wartell+pt(a)gmail.com>: This is related to http://bugs.python.org/issue8601 "bz2.BZ2File should support "with" protocol per PEP 343" The documentation at http://docs.python.org/library/bz2.html states: "This module provides a comprehensive interface for the bz2 compression library. It implements a complete file interface,..." although bz2.BZ2File does not support the __enter__ and __exit__ methods so arguably doesn't implement the "complete … [View More]

3 5

[issue8638] Remove suggestion for name mangling from the tutorial
by Lucian Ursu July 31, 2010

July 31, 2010

New submission from Lucian Ursu <lucian_ursu(a)yahoo.com>: I suggest that name mangling should not be recommended as a way of having private attributes. Instead, one underscore should be suggested as a signal that the attribute is private. This suggestion comes after discussing with some of the helpers from #python. Basically, they said that name mangling should never be used, so it would be appropriate to remove this recommendation from the tutorial. ---------- assignee: docs@python … [View More]

8 8

[issue8564] Update documentation on doctest/unittest2 integration
by Peter Fein July 10, 2010

July 10, 2010

New submission from Peter Fein <pfein(a)pobox.com>: The documentation on integrating doctests in a file of unittests is confusing and out of date. This patch updates the documentation to use unittest2 test discovery. ---------- assignee: docs@python components: Documentation files: doctest_unittest_integration_doc.diff keywords: patch messages: 104468 nosy: docs@python, pfein priority: normal severity: normal status: open title: Update documentation on doctest/unittest2 integration … [View More]

5 6

[issue8653] urlparse.urlparse/urlsplit doc missing
by Dave Abrahams June 28, 2010

June 28, 2010

New submission from Dave Abrahams <dave(a)boostpro.com>: The docstrings for these functions don't explain the 'scheme' parameter. Even renaming it to default_scheme would help. ---------- assignee: docs@python components: Documentation messages: 105221 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: urlparse.urlparse/urlsplit doc missing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8653> _______________________________________

5 8