Mailman 3 October 2012 - docs

[issue13282] the table of contents in epub file is too long
by wrobell 11 Apr '19

11 Apr '19

New submission from wrobell <wrobell(a)pld-linux.org>: the table of contents in python documentation epub file is very very long. it takes several long minutes to jump from first page to a part containing language reference toc. imho it would be great if first page of epub file contained pointers to tutorial, lang ref, mod ref without detailed table of contents as it is at docs.python.org. ---------- assignee: docs@python components: Documentation messages: 146548 nosy: docs@python, wrobell priority: normal severity: normal status: open title: the table of contents in epub file is too long versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13282> _______________________________________

4 4

[issue13850] Summary tables for argparse add_argument options
by Nick Coghlan 24 Mar '19

24 Mar '19

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements: 1. Summary table with a one line description of each parameter 2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const') 3. Summary table with a one line description of each alternative for the "nargs" parameter ---------- assignee: docs@python components: Documentation messages: 151880 nosy: bethard, docs@python, ncoghlan priority: normal severity: normal status: open title: Summary tables for argparse add_argument options versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________

12 27

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan 20 Mar '19

20 Mar '19

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 15 Mar '19

15 Mar '19

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 15 Mar '19

15 Mar '19

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 15 Mar '19

15 Mar '19

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

[issue11776] types.MethodType() params and usage is not documented
by anatoly techtonik 24 Feb '19

24 Feb '19

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 24 Feb '19

24 Feb '19

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 24 Feb '19

24 Feb '19

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

[issue15457] consistent treatment of generator terminology
by Chris Jerdonek 04 Jan '19

04 Jan '19

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: The documentation on generators (outside of PEP 255) does not currently educate the reader on the more specific "generator function" and "generator iterator" terminology, or at least not in any consistent or systematic way. For example, the glossary includes only a single entry for "generator," and that entry does not mention the two more specific forms. I think it would help for general discourse purposes if this distinction were made clearer, while still continuing to allow for the use of the generic word "generator" when the context makes it clear. There are also cases where index entries can be improved in this regard, and where references to the section containing details about generators can still be added. I am in the process of completing a proposed patch. ---------- assignee: docs@python components: Documentation keywords: easy messages: 166474 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: consistent treatment of generator terminology versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15457> _______________________________________

4 12