Mailman 3 June 2015 - docs

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

17 Nov '20

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

[issue13561] os.listdir documentation should mention surrogateescape
by Michael Foord 16 Nov '20

16 Nov '20

New submission from Michael Foord <michael(a)voidspace.org.uk>: Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example). This should be documented. ---------- assignee: docs@python components: Documentation messages: 149070 nosy: docs@python, michael.foord priority: normal severity: normal stage: needs patch status: open title: os.listdir documentation should mention surrogateescape versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13561> _______________________________________

5 6

[issue14338] urllib2 HowTo for overriding post/3xx behavior.
by beeNuts 15 Nov '20

15 Nov '20

New submission from beeNuts <jeff.adams(a)linux.com>: Issue #14144, with the title "urllib2 HTTPRedirectHandler not forwarding POST data in redirect" was recently closed with these comments: "This could be cookbook recipe style example, if it's utility value is high. I am closing this issue as I feel that the requirement may not be addressed by a change. If there is patch for HowTo, we can tackle that in another issue. Thank you for contribution." The decision that documents on this issue were preferable to a patch seems like a fair compromise, especially considering that the RFC is decidedly ambiguous.I was wondering if the HowTo would be forthcoming? It seems to me that the value/utility would certainly be high. I'd submit it myself but I'm so new to Python that I don't trust my ability to do it correctly. It's something I would find highly useful, though. ---------- assignee: docs@python components: Documentation messages: 156080 nosy: beerNuts, docs@python priority: normal severity: normal status: open title: urllib2 HowTo for overriding post/3xx behavior. versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14338> _______________________________________

4 4

[issue17437] Difference between open and codecs.open
by Giampaolo Rodola' 15 Nov '20

15 Nov '20

New submission from Giampaolo Rodola': In Python 2 the distinction between open() and codes.open() was clear because 'encoding' and 'errors' args were provided by codecs.open only. This is no longer the case in Python 3 since both args are provided also by open(). I'm probably missing something but regardless I think codecs.open doc [1] should be more clear as to when and why (say) codecs.open(file, encoding='utf8', errors='ignore') should be preferred over open(file, encoding='utf8', errors='ignore'). [1] http://docs.python.org/3/library/codecs.html#codecs.open ---------- assignee: docs@python components: Documentation messages: 184303 nosy: docs@python, ezio.melotti, giampaolo.rodola priority: normal severity: normal status: open title: Difference between open and codecs.open versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17437> _______________________________________

3 2

[issue10709] Misc/AIX-NOTES needs updating
by Antoine Pitrou 11 Nov '20

11 Nov '20

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

[issue15034] tutorial should use best practices in user defined execeptions section
by R. David Murray 11 Nov '20

11 Nov '20

New submission from R. David Murray <rdmurray(a)bitdance.com>: And I wish I knew what those were. ---------- assignee: docs@python components: Documentation messages: 162513 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: tutorial should use best practices in user defined execeptions section type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15034> _______________________________________

11 16

[issue10529] Write argparse i18n howto
by Éric Araujo 07 Nov '20

07 Nov '20

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

[issue14003] __self__ on built-in functions is not as documented
by Роман Донченко 07 Nov '20

07 Nov '20

New submission from Роман Донченко <DXDragon(a)yandex.ru>: The language reference says this in section 3.2: ~ Built-in functions A built-in function object is a wrapper around a C function. Examples of built-in functions are len() and math.sin() <...> Special read-only attributes: <...> __self__ is set to None (but see the next item) <...>. ~ That is not the case: ActivePython 3.2.2.3 (ActiveState Software Inc.) based on Python 3.2.2 (default, Sep 8 2011, 10:55:13) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> len.__self__ <module 'builtins' (built-in)> >>> open.__self__ <module 'io' (built-in)> >>> import math >>> math.sin.__self__ <module 'math' (built-in)> ---------- assignee: docs@python components: Documentation messages: 153287 nosy: SpecLad, docs@python priority: normal severity: normal status: open title: __self__ on built-in functions is not as documented type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14003> _______________________________________

12 12

[issue15693] expose glossary link on hover
by Chris Jerdonek 06 Nov '20

06 Nov '20

New submission from Chris Jerdonek: It would be nice if hovering over the right side of the header to a glossary entry would expose a link in the same way that it does for function definitions, etc. http://docs.python.org/dev/glossary.html#glossary Otherwise, there doesn't seem to be a convenient way to get a direct link to a glossary entry. I'm not sure if this issue should also be filed with Sphinx. ---------- assignee: docs@python components: Documentation messages: 168388 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: expose glossary link on hover type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15693> _______________________________________

7 15

[issue16834] ioctl mutate_flag behavior in regard to the buffer size limit
by Yuval Weinbaum 06 Nov '20

06 Nov '20

New submission from Yuval Weinbaum: In fcntl module, the documentation states the following regarding the mutate_flag in ioctl method: *** If it is false, the buffer’s mutability is ignored and behaviour is as for a read-only buffer, except that the 1024 byte limit mentioned above is avoided – so long as the buffer you pass is as least as long as what the operating system wants to put there, things should work. *** However, looking at the code (fcntlmodule.c) it seems that the 1024 bytes limitation is avoided when the mutate_flag is set to True (the opposite of what is stated in the doc). ---------- assignee: docs@python components: Documentation messages: 178732 nosy: Yuval.Weinbaum, docs@python priority: normal severity: normal status: open title: ioctl mutate_flag behavior in regard to the buffer size limit versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16834> _______________________________________

4 4