Mailman 3 May 2014 - docs

[issue18355] Merge super() guide into documentation
by Russkel 08 Jun '19

08 Jun '19

New submission from Russkel: When looking for documentation on the correct usage on super (http://docs.python.org/2/library/functions.html?highlight=super#super), the documentation links to this rather will written blog post http://rhettinger.wordpress.com/2011/05/26/super-considered-super/ by Mr. Hettinger. I think there is value in merging that blog post into a HOWTO and including in the official documentation. I'm more than willing to create a patch if this is considered a good idea. ---------- assignee: docs@python components: Documentation messages: 192262 nosy: Russkel, docs@python, rhettinger priority: normal severity: normal status: open title: Merge super() guide into documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18355> _______________________________________

5 7

[issue19184] dis module has incorrect docs for RAISE_VARARGS
by Ned Batchelder 03 Jun '19

03 Jun '19

New submission from Ned Batchelder: The order of values on the stack is backwards for RAISE_VARARGS. The docs say: "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS." But in fact, the order is reverse of that. In the one-parameter case, the exception is TOS, in the two-parameter case, the value is TOS, and in the three-parameter case, the traceback is TOS. Not sure how to write that concisely, thought. :) ---------- assignee: docs@python components: Documentation keywords: easy messages: 199096 nosy: docs@python, nedbat priority: normal severity: normal status: open title: dis module has incorrect docs for RAISE_VARARGS versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________

9 16

[issue21314] Bizarre help
by Vedran Čačić 31 May '19

31 May '19

New submission from Vedran Čačić: Please look at the output of help(object.__ge__). 1. What's that $ in front of self? lt and gt don't have it. 2. What's that / as a third argument? Many wrapper functions have it (for example, see help(tuple.__len__). 3. What's that -- as the first line of doc? Similar methods don't have it. ---------- assignee: docs@python components: Documentation messages: 216899 nosy: Vedran.Čačić, docs@python priority: normal severity: normal status: open title: Bizarre help versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21314> _______________________________________

18 31

[issue19175] Erroneous reference to "integer" in format string grammar
by David Chambers 17 May '19

17 May '19

New submission from David Chambers: I first raised this issue on Stack Overflow: http://stackoverflow.com/questions/19203194 The [replacement field grammar][1] states that an [integer][2] is a valid field_name, but this is inaccurate: >>> '{0}'.format('zero') 'zero' >>> '{0x0}.format('zero') KeyError: '0x0' >>> '{0o0}.format('zero') KeyError: '0o0' >>> '{0b0}.format('zero') KeyError: '0b0' This [comment][3] by Eric Smith suggests that the above is the intended behaviour: > get_integer uses the narrowest possible definition for integer indexes, > in order to pass all other strings to mappings. The documentation should be updated to match the actual behaviour. abarnert on Stack Overflow suggested the following change: -arg_name ::= [identifier | integer] +arg_name ::= [identifier | digit+] [1]: http://docs.python.org/2/library/string.html#format-string-syntax [2]: http://docs.python.org/2/reference/lexical_analysis.html#grammar-token-inte… [3]: http://bugs.python.org/issue8985#msg107705 ---------- assignee: docs@python components: Documentation messages: 199024 nosy: davidchambers, docs@python priority: normal severity: normal status: open title: Erroneous reference to "integer" in format string grammar 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/issue19175> _______________________________________

3 3

[issue21202] Naming a file` io.py` causes cryptic error message
by Madison May 15 May '19

15 May '19

New submission from Madison May: Naming a file `io.py` in the root directory of a project causes the following error on 2.7: AttributeError: 'module' object has no attribute 'BufferedIOBase' Similar issues arise on 3.x., although the error message is a bit more useful: Fatal Python error: Py_Initialize: can't initialize sys standard streams AttributeError: 'module' object has no attribute 'OpenWrapper' At the very least we should ensure that the error message is a bit more straightforward and clear, as I imagine its not all that uncommon to cause this kind of conflict. ---------- assignee: docs@python components: Documentation, IO messages: 215940 nosy: docs@python, madison.may priority: normal severity: normal status: open title: Naming a file` io.py` causes cryptic error message versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21202> _______________________________________

9 13

[issue18478] Class bodies: when does a name become local?
by Terry J. Reedy 14 May '19

14 May '19

New submission from Terry J. Reedy: http://docs.python.org/3/reference/executionmodel.html#naming-and-binding says "The following are blocks: ... a class definition." and "If a name binding operation occurs anywhere within a code block, all uses of the name within the block are treated as references to the current block. This can lead to errors when a name is used within a block before it is bound. ..." This is definitely true for functions, but not for classes: foo = 'bar' class C: foo = foo print(C().foo) # bar This is the same for 3.3 and 2.7 with and without '(object)' added. Unless the code is considered to be buggy (probably since forever), the doc should be modified to change 'code block' to 'function code block' or maybe 'module or function code block'. (At near as I can think, the statement is true for modules, but only because globals() == locals(), so that part of the issue does not arise.) ---------- assignee: docs@python components: Documentation messages: 193205 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Class bodies: when does a name become local? type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18478> _______________________________________

5 11

[issue13286] PEP 3151 breaks backward compatibility: it should be documented
by STINNER Victor 13 May '19

13 May '19

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The following example works on Python 2.7 and 3.2, but fails on Python 3.3: ----------- import errno import os try: os.rmdir("testdir") except: pass os.mkdir("testdir") try: try: os.mkdir("testdir") except IOError as exc: # If can't get proper access, then just forget about writing # the data. if exc.errno == errno.EACCES: pass else: raise except OSError as exc: # Probably another Python process already created the dir. if exc.errno == errno.EEXIST: pass else: raise except Exception: print("PEP 3151 broke backward compatibility on such pattern!") ----------- I noticed the problem while reading the changeset e4d44c2e8e81. ---------- assignee: docs@python components: Documentation messages: 146562 nosy: docs@python, flox, haypo, pitrou priority: normal severity: normal status: open title: PEP 3151 breaks backward compatibility: it should be documented versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13286> _______________________________________

5 8

[issue10536] Enhancements to gettext docs
by Éric Araujo 10 May '19

10 May '19

New submission from Éric Araujo <merwok(a)netwok.org>: A patch made for #2504 revealed a bug in gettext.rst, and I’ve found a number of other things to change in the file. This is the first patch of a series of two or three. Barry, as the original author of the module and doc, I’d like your opinion on points 3, a, and b particularly. Patch is also uploaded to Rietveld for greater convenience: http://codereview.appspot.com/3333042/ (upload.py rocks) Summary: 1) Markup: Use modern class/method directives combo (yay DRY). Mark up variable parts in :file: constructs (e.g. :file:`{domain}.mo` will cause the HTML output to use var to indicate replaceable text). Also change some ``gettext`` to :program:`gettext` for consistency. 2) Fix a typo in lngettext doc (originally included in patch by Franz Glasner for #2504). 3) I had started to remove information about private attributes (_info, _charset), advertising public getter methods instead. Then I read the description of NullTranslations and realized the information was needed for subclasses. I’ve reverted my removals, but I still think the private attributes should be listed in a specific section for people writing subclasses and not in the rest of the text. If you’re okay, I’ll make a second patch. 4) Assorted wording changes, missing periods and hyphens, and other very small touch-ups: Turned a broken bare link into a working link with nice text; used the with statement in an example (we all love the with statement!); used two spaces after periods throughout (hello Fred Drake). Final note: lines have not been rewrapped, for diff clarity. When I commit part or all of this patch, I’ll make another commit to rewrap. Not addressed: a) The current docs is currently POSIX-specific. b) The docs take great care to explain that Unicode strings will be returned in different places, but this should not be so accented in 3.x docs IMO. I would just put a note somewhere near the top that all strings are str and remove the redundant sentences. Following that line of thought, I could group all l*gettext variants at the end of the list of methods, explaining that regular usage should just be happy with str objects and that l*gettext are available if people really want bytes. c) The file uses “built-in namespace” and “builtins namespace”, sometimes in neighbor paragraphs. :mod:`builtins` is not used, even in explanations of the install function/method. I don’t know if I should change that. d) Some capitalization patterns look strange to me: I have seen “I18N” and “L10N” in upper case nowhere else. Similarly, lower-case “id” looks stranger than “ID”. The latter is used for example in official GNU gettext docs. Am I going into foolish consistency territory or not? Thanks in advance for reviews and opinions. ---------- assignee: eric.araujo components: Documentation files: gettext-docs-1.diff keywords: needs review, patch messages: 122420 nosy: barry, docs@python, eric.araujo priority: normal severity: normal stage: patch review status: open title: Enhancements to gettext docs versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file19819/gettext-docs-1.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10536> _______________________________________

8 17

[issue12188] PEP 7, C style: add ++ policy and explanation
by Terry J. Reedy 09 May '19

09 May '19

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: In response to a discussion of a patch removing 'useless' post-increments, (which issue has apparently come up before) Guido posted "> Sorry to butt in here, but I agree with Eric that it was better > before. There is a common idiom, *pointer++ =<something>, and > whenever you see that you know that you are appending something to an > output buffer. Perhaps the most important idea here is that this > maintains the *invariant* "pointer points just after the last thing in > the buffer". Always maintaining the invariant is better than trying to > micro-optimize things so as to avoid updating dead values. The > compiler is better at that." A condensed version of the above added to PEP 7 would help new developers see the usage as local idiom rather than style bug. ---------- assignee: docs@python components: Documentation messages: 136991 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: PEP 7, C style: add ++ policy and explanation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12188> _______________________________________

7 11

[issue20709] os.utime(path_to_directory): wrong documentation for Windows.
by Jan-Philip Gehrcke 08 May '19

08 May '19

New submission from Jan-Philip Gehrcke: The os.utime() docs for Python 2 (http://docs.python.org/2/library/os.html#os.utime) and 3 (http://docs.python.org/3/library/os.html#os.utime) both contain the sentence "Whether a directory can be given for path depends on whether the operating system implements directories as files (for example, *Windows does not*)" "Windoes does not" is wrong. CPython 2.7 on Windows 7: >>> os.utime(".", (100, 100)) >>> os.stat(".").st_mtime 100.0 We should - either name a specific system for which this does not work - or remove this example. Windows XP and newer support this operation via SetFileTime (http://msdn.microsoft.com/en-us/library/windows/desktop/ms724933%28v=vs.85%…): "Sets the date and time that the specified file or directory was created, last accessed, or last modified." I have grepped myself through a couple of CPython source trees and found posixmodule.c: if (!SetFileTime(hFile, NULL, &atime, &mtime) in 2.5, 2.6, 2.7. I guess the statement comes from 2.4 times, where `SetFileTime` only appears in `PC/bdist_wininst/extract.c`. So, do we just remove the hint or does someone have an example at hand for which combination of Python and platform this does not work for directories? Once we have a decision, I will be happy to provide the mini patch. ---------- assignee: docs@python components: Documentation messages: 211760 nosy: docs@python, jgehrcke priority: normal severity: normal status: open title: os.utime(path_to_directory): wrong documentation for Windows. versions: 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/issue20709> _______________________________________

7 14