Mailman 3 February 2014 - docs

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan March 21, 2019

March 21, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: pydoc is installed as a script by Python. It should be documented under http://docs.python.org/dev/using/index.html. ---------- assignee: docs@python components: Documentation messages: 161831 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for pydoc type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14944> _______________________________________

7 13

[issue13231] sys.settrace - document 'some other code blocks' for 'call' event type
by anatoly techtonik March 16, 2019

March 16, 2019

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/sys.html#sys.settrace While writing settrace function you need to know what kind of data is expected and how to get more information about it. Current documentation for sys.settrace doesn't give too much answers. To improve that situation at least with 'call' event: 1. Link 'frame' to the middle of table on inspect module page [1] 2. List all possible 'code blocks' for 'call' event (I know there is module in addition to function) 3. Provide example how to extract popular data for corresponding 'code block' (name for functions, name for modules, name for classes/methods, relative file path, line no, how to detect labmbda function) in a safe manner (inspect page contains some FUD about memory usage) 1. http://docs.python.org/library/inspect#types-and-members ---------- assignee: docs@python components: Documentation messages: 146009 nosy: docs@python, techtonik priority: normal severity: normal status: open title: sys.settrace - document 'some other code blocks' for 'call' event type _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13231> _______________________________________

2 2

[issue13277] tzinfo subclasses information
by Senthil Kumaran March 16, 2019

March 16, 2019

New submission from Senthil Kumaran <senthil(a)uthcode.com>: This was in the docs mailing list, not translated to bug report Paul Koning wrote: Section 8.1.6 of the library manual talks about utcoffset(dt)-dst(dt) as the "standard offset" and says that this should not depend on the date or +time but only on the location. This is not true as there cases were certain locations changed the time offsets as per their convenience. It is either a doc fix to remove that sentence if the datetime.astimezone does not depend upon utcoffset(dt)-dst(dt), or if it does, then it is a code fix. ---------- assignee: docs@python messages: 146501 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: tzinfo subclasses information type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13277> _______________________________________

5 5

[issue13074] Improve documentation of locale encoding functions
by Geoffrey Bache March 16, 2019

March 16, 2019

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: The locale module provides locale.getdefaultlocale and locale.getpreferredencoding. The encodings returned by each are generally subtly different ('ISO8859-1' vs 'ISO-8859-1'), but the difference between these methods is not explained. A comment by Martin von Löwis from 2003 in http://bugs.python.org/issue813449 indicates that "getdefaultlocale should not be used in new code", if this is really the case then this should be in the docs. Anyone reading the docs from the top will currently encounter getdefaultlocale first and believe that this is the way to get the encoding. ---------- assignee: docs@python components: Documentation messages: 144677 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Improve documentation of locale encoding functions versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13074> _______________________________________

5 5

[issue20749] shutil.unpack_archive(): security concerns not documented
by Jakub Wilk March 16, 2019

March 16, 2019

New submission from Jakub Wilk: shutil.unpack_archive() uses tarfile.extractall() under the hood, so it's not suitable for unpacking untrusted archives. But this fact is not documented. Please add a security warning to shutil.unpack_archive() documentation. ---------- assignee: docs@python components: Documentation messages: 212029 nosy: docs@python, jwilk priority: normal severity: normal status: open title: shutil.unpack_archive(): security concerns not documented _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20749> _______________________________________

3 3

[issue11776] types.MethodType() params and usage is not documented
by anatoly techtonik Feb. 25, 2019

Feb. 25, 2019

New submission from anatoly techtonik <techtonik(a)gmail.com>: types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented. ---------- assignee: docs@python components: Documentation messages: 133089 nosy: docs@python, techtonik priority: normal severity: normal status: open title: types.MethodType() params and usage is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________

13 31

[issue13456] Providing a custom HTTPResponse class to HTTPConnection
by R. David Murray Feb. 25, 2019

Feb. 25, 2019

New submission from R. David Murray <rdmurray(a)bitdance.com>: The doc string for HTTPConnection.getresponse mentions (in broken English) that the instance's response_class attribute determines what class gets instantiated for a response. The docs do not mention this attribute, nor any other way to control what class is used. Since this attribute already exists and is mentioned in the doc string, can we consider this a doc error and just document it? ---------- assignee: docs@python components: Documentation messages: 148136 nosy: docs@python, orsenthil, r.david.murray priority: normal severity: normal status: open title: Providing a custom HTTPResponse class to HTTPConnection versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13456> _______________________________________

5 5

[issue11352] Buf in cgi module doc
by Pierre Quentel Feb. 25, 2019

Feb. 25, 2019

New submission from Pierre Quentel <pierre.quentel(a)gmail.com>: Hi, I wrote a patch for the cgi module in version 3.2rc1 (#4953). Small changes should be done to the documentation of this module to reflect the changes in the module API : - in section "20.2.2. Using the cgi module" original text : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:" proposed new text (for files, value is bytes, not string, and the read() method on file also returns bytes) : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as bytes. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute (the read() and readline() methods will return bytes) :" - version 3.2 introduced a parameter "encoding" for the FieldStorage constructor, used to decode the bytes received on the HTTP connection for fields other than files. This encoding must the one defined in the HTML document holding the form submitted to the CGI script ; it is usually defined by a meta tag : <meta http-equiv="Content-type" content="text/html;charset=latin-1"> or by the Content-Type header for this document I'm not sure where this should be mentioned in the module documentation. Maybe in "20.2.9. Common problems and solutions" for the moment. But there are plans (#11066) to introduce another interface to change the encoding of sys.stdout in the CGI script itself, so another option would be to open a specific section about encodings Hope it's clear enough Pierre ---------- assignee: docs@python components: Documentation messages: 129691 nosy: docs@python, quentel priority: normal severity: normal status: open title: Buf in cgi module doc type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________

14 27

[issue19953] __iadd__() doc not strictly correct
by ferno Feb. 7, 2019

Feb. 7, 2019

New submission from ferno: Document in question is: http://docs.python.org/3.3/reference/datamodel.html#object.__iadd__ The documentation states, to execute the statement x += y, where x is an instance of a class that has an __iadd__() method, x.__iadd__(y) is called. However, this doesn't appear to be strictly true. According to this, the following well-known example: >>> a = (1, [2, 3]) >>> a[1] += [4, 5] Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'tuple' object does not support item assignment >>> a (1, [2, 3, 4, 5]) should give the same behaviour as: >>> a = (1, [2, 3]) >>> a[1].__iadd__([4, 5]) [2, 3, 4, 5] >>> a (1, [2, 3, 4, 5]) However, this snippet DOES give the identical behaviour: >>> a = (1, [2, 3]) >>> a[1] = a[1].__iadd__([4, 5]) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'tuple' object does not support item assignment >>> a (1, [2, 3, 4, 5]) which leads me to suggest that this line of the documentation should be adjusted to read: to execute the statement x += y, where x is an instance of a class that has an __iadd__() method, x = x.__iadd__(y) is called. This fix would incidentally harmonise with the documentation for operator.iadd() et al., (http://docs.python.org/3.3/library/operator.html#operator.iadd), which had a similar problem but was corrected following issue 7259 (http://bugs.python.org/issue7259), now reading: a = iadd(a, b) is equivalent to a += b. ---------- assignee: docs@python components: Documentation messages: 205920 nosy: docs@python, ferno priority: normal severity: normal status: open title: __iadd__() doc not strictly correct versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19953> _______________________________________

6 10

[issue20001] pathlib inheritance diagram too large
by Antoine Pitrou Feb. 5, 2019

Feb. 5, 2019

New submission from Antoine Pitrou: The inheritance diagram at http://docs.python.org/dev/library/pathlib.html is too large, it can easily take up half the vertical space (or perhaps all of it on a smaller screen). The font size looks fine, it's just that there's a lot of spacing around. (of course, the style could perhaps also be changed or improved) ---------- assignee: docs@python components: Documentation messages: 206354 nosy: docs@python, eli.bendersky, georg.brandl, pitrou priority: low severity: normal status: open title: pathlib inheritance diagram too large versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20001> _______________________________________

7 11