Mailman 3 April 2015 - docs

Re: [docs] Bug - 4.7.7
by Tim Golden April 13, 2015

April 13, 2015

[Keeping the conversation cc-ed to docs@ for the benefit of the other docs admins] On 13/04/2015 13:36, Tronster wrote: > Hi Tim, thanks for the quick reply. > > These language overview documents are great; some of the cleanest and > clearest I've read for any language. Thanks; nice of you to say so. > The compiling looks like it's due to PyCharm using Python 2.6; thank you > for mentioning this works under 3.4 ... I'll be looking into getting on > that version (right now just using the default PyCharm install.) Excellent. > > As for making sense... I just don't understand why a string is passed to > an integer, unless that's the point; that Python isn't strongly typed > and that even though something is labeled an 'int' a string can be > passed. If that is the case; there is a lot of things happening in that > example; perhaps break it out (e.g., single argument function, showing > how the type is override.) Ok; now I understand your concerns rather better. I agree that the example is cramming rather a lot in. In particular, the unexplained "eggs: int = 'spam'" param is highlighting the complete optionality of the annotation. In this example, the annotation looks as if it might well be used for some sort of parameter validation or optimisation. But in current versions of Python, none of the built-in functionality makes any use of it. It would be perfectly valid to have an annotation which was a max/min value pair, or a longer explanation of the parameter's meaning, or a GUID which could be used to represent it to some remote system. Or anything. Unless one of the other docs maintainers has a view, I'll dig a little into that particular section to see who set it up in the first place before I wade in to make changes, but I agree that it is probably too confusing for a tutorial. TJG > > Cheers. > > > Tronster > http://tronster.com > 410-299-6348

2 4

Bug - 4.7.7
by Tronster April 13, 2015

April 13, 2015

For someone learning Python, the sample itself doesn't make sense. https://docs.python.org/3/tutorial/controlflow.html <https://docs.python.org/3/tutorial/controlflow.html> 4.7.7 Function Annotations Typed in program in PyCharm and received the following: >>> def f(ham:42, eggs:int='spam') ->"Nothing to see here": ... print("Annotations:", f.__annotations__) ... print("Arguements:", ham,eggs) ... File "<input>", line 1 def f(ham:42, eggs:int='spam') ->"Nothing to see here": ^ SyntaxError: invalid syntax

2 1

docs@ InfiniteLoop in example on website
by Abhinav Tyagi April 13, 2015

April 13, 2015

Following example in Section 4.2 would run into infinite loop. https://docs.python.org/2/tutorial/controlflow.html#for-statements >>> for w in words[:]: # Loop over a slice copy of the entire list.... if len(w) > 6:... words.insert(0, w)...>>> words['defenestrate', 'cat', 'window', 'defenestrate'] Should be something like this (but still leaves duplicate elements in the list): ----------------------------------- words_tmp = copy.deepcopy(words) for w in words_tmp: if len(w)>6 : words.insert(0,w) ----------------------------------- Thanks & Regards Abhinav Tyagi

2 3

[issue17380] initproc return value is unclear
by Zbyszek Jędrzejewski-Szmek April 13, 2015

April 13, 2015

New submission from Zbyszek Jędrzejewski-Szmek: initproc is declared to return an int, but what returned values mean is not documented. Noddy_init in http://docs.python.org/3/extending/newtypes.html?highlight=initproc#adding-… can be seen to return 0 on success and -1 on error, but that's about it. Also, when I wrote a function which return 1 on error, on every second invocation the exception would be ignored: static int Reader_init(Reader *self, PyObject *args, PyObject *keywds) { ... if (flags && path) { PyErr_SetString(PyExc_ValueError, "cannot use both flags and path"); return 1; } ... } >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError I'm not sure how to interpret this since I couldn't find the documentation for the expected value. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 183689 nosy: docs@python, zbysz priority: normal severity: normal status: open title: initproc return value is unclear type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17380> _______________________________________

6 9

[issue23915] traceback set with BaseException.with_traceback() overwritten on raise
by R. David Murray April 13, 2015

April 13, 2015

R. David Murray added the comment: Yes, a doc note would be a good idea, I think. ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python resolution: not a bug -> status: closed -> open versions: -Python 3.2, Python 3.3, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23915> _______________________________________

1 0

Re: [docs] Standardize documentation whitespace, formatting (issue 23921)
by jheiv＠jheiv.com April 12, 2015

April 12, 2015

Reviewers: berkerpeksag, http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst File Doc/howto/curses.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst#newcode… Doc/howto/curses.rst:182: (height, width) = (5, 40) On 2015/04/12 11:17:30, berkerpeksag wrote: > () is not needed: > > begin_x, begin_y = (20, 7) > > is a valid Python code. This was the most substantiate change I made in the patch -- I believe it was the only place where I violated my rule of "whitespace only". I wrapped the LHS in parens in an attempt to make it more new-user-friendly. I originally has what you wrote: a, b = (c, d) But, after looking at it, I was afraid that new users would get this confused with a = b = (c, d) This concern may not be founded of course, but just explaining the thought process behind the change. http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst File Doc/howto/regex.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst#newcode1… Doc/howto/regex.rst:1117: >>> p = re.compile( '(blue|white|red)' ) On 2015/04/12 11:17:30, berkerpeksag wrote: > p = re.compile('(blue|white|red)') > > Drop the trailing spaces please. I agree, the reason for keeping it like this ( <- with spaces -> ) is only because the author originally had a leading space before the arguments and no trailing space after. I tried to change as little as possible, so instead of removing the leading space, I added a trailing space for balance. But I agree that there should be neither. http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst File Doc/library/subprocess.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst#n… Doc/library/subprocess.rst:942: # ==> On 2015/04/12 11:17:30, berkerpeksag wrote: > Perhaps ``# becomes`` or something like that would be better here. The `# becomes` style is actually used earlier in the document: https://docs.python.org/3/library/subprocess.html#replacing-bin-sh-shell-ba… I'm not sure why it changes part way through either. http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.r… File Doc/reference/simple_stmts.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.r… Doc/reference/simple_stmts.rst:334: if not expression: raise AssertionError On 2015/04/12 11:17:30, berkerpeksag wrote: > if not expression: > raise AssertionError Yes, this would be the most compliant, and I can change this. Because of the many lines of code in the docs that contain what I called "trival blocks" in-line with conditions, I had to start conditionally ignoring them. if <cond>: <trivial block> Ended up getting ignored, provided that <trivial block> was exactly "pass", "continue", "break", or (less trivially) started with "print" or "raise". Please review this at http://bugs.python.org/review/23921/ Affected files: Doc/distutils/apiref.rst Doc/faq/design.rst Doc/faq/library.rst Doc/faq/programming.rst Doc/howto/curses.rst Doc/howto/descriptor.rst Doc/howto/functional.rst Doc/howto/logging-cookbook.rst Doc/howto/logging.rst Doc/howto/regex.rst Doc/howto/unicode.rst Doc/howto/urllib2.rst Doc/howto/webservers.rst Doc/library/abc.rst Doc/library/argparse.rst Doc/library/asynchat.rst Doc/library/asyncio-sync.rst Doc/library/asyncore.rst Doc/library/audioop.rst Doc/library/collections.abc.rst Doc/library/collections.rst Doc/library/concurrent.futures.rst Doc/library/configparser.rst Doc/library/contextlib.rst Doc/library/crypt.rst Doc/library/ctypes.rst Doc/library/email.headerregistry.rst Doc/library/getopt.rst Doc/library/html.parser.rst Doc/library/http.client.rst Doc/library/inspect.rst Doc/library/ipaddress.rst Doc/library/locale.rst Doc/library/mailcap.rst Doc/library/mmap.rst Doc/library/multiprocessing.rst Doc/library/optparse.rst Doc/library/re.rst Doc/library/shelve.rst Doc/library/ssl.rst Doc/library/string.rst Doc/library/subprocess.rst Doc/library/threading.rst Doc/library/tkinter.rst Doc/library/tokenize.rst Doc/library/types.rst Doc/library/unittest.rst Doc/library/urllib.request.rst Doc/library/wsgiref.rst Doc/library/xml.dom.minidom.rst Doc/library/xml.etree.elementtree.rst Doc/library/xmlrpc.client.rst Doc/reference/datamodel.rst Doc/reference/expressions.rst Doc/reference/simple_stmts.rst Doc/tutorial/appendix.rst Doc/tutorial/classes.rst Doc/tutorial/controlflow.rst Doc/tutorial/errors.rst Doc/tutorial/inputoutput.rst Doc/tutorial/introduction.rst Doc/tutorial/modules.rst Doc/tutorial/stdlib.rst Doc/tutorial/stdlib2.rst Doc/whatsnew/3.2.rst Doc/whatsnew/3.3.rst Doc/whatsnew/3.4.rst

1 0

[issue12955] urllib2.build_opener().open() is not friendly to "with ... as:"
by Valery Khamenya April 12, 2015

April 12, 2015

New submission from Valery Khamenya <khamenya(a)gmail.com>: The following intuitive construction with urllib2.build_opener().open() as: ... leads to AttributeError: addinfourl instance has no attribute '__exit__' http://docs.python.org/library/urllib2.html says almost nothing about concept of closing. Could it be possible to add a canonical "with ... as:" example for urllib2.build_opener() ? Thanks, Valery ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 143836 nosy: Valery.Khamenya, docs@python priority: normal severity: normal status: open title: urllib2.build_opener().open() is not friendly to "with ... as:" type: resource usage 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/issue12955> _______________________________________

9 17

Standardize documentation whitespace, formatting (issue 23921)
by berker.peksag＠gmail.com April 12, 2015

April 12, 2015

http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst File Doc/faq/programming.rst (left): http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#oldc… Doc/faq/programming.rst:1102: Use the :func:`reversed` built-in function, which is new in Python 2.4:: I'd drop the "which is new in Python 2.4" part. http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#oldc… Doc/faq/programming.rst:1110: With Python 2.3, you can use an extended slice syntax:: I'd remove this part entirely. Python 2.3 is dead :) http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst File Doc/faq/programming.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#newc… Doc/faq/programming.rst:668: >>> print(b) Thanks for the patch! If you adding >>> here, you'll also need to add to the whole example. And print() is redundant here. >>> class B: pass ... >>> b = B() >>> b <__main__.B object at 0x7f8273825740> http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#newc… Doc/faq/programming.rst:1106: # ... do something with x ... I'm not fan of ``# do something`` type of comments. We can just print ``x`` here. http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst File Doc/howto/curses.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst#newcode… Doc/howto/curses.rst:182: (height, width) = (5, 40) () is not needed: begin_x, begin_y = (20, 7) is a valid Python code. http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst File Doc/howto/functional.rst (left): http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst#old… Doc/howto/functional.rst:397: if not (condition2): if not condition2: http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst#old… Doc/howto/functional.rst:399: ... # ... http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst File Doc/howto/functional.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst#new… Doc/howto/functional.rst:401: if not (conditionN): if not conditionN: http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst File Doc/howto/regex.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst#newcode1… Doc/howto/regex.rst:1117: >>> p = re.compile( '(blue|white|red)' ) p = re.compile('(blue|white|red)') Drop the trailing spaces please. http://bugs.python.org/review/23921/diff/14500/Doc/howto/webservers.rst File Doc/howto/webservers.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/howto/webservers.rst#new… Doc/howto/webservers.rst:298: yield '<tr><th>{0}</th><td>{1}</td></tr>'.format( {0} and {1} can be written like {}. http://bugs.python.org/review/23921/diff/14500/Doc/library/collections.abc.… File Doc/library/collections.abc.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/library/collections.abc.… Doc/library/collections.abc.rst:143: ''' Alternate set implementation favoring space over speed I'd use """ and remove the trailing spaces. http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst File Doc/library/subprocess.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst#n… Doc/library/subprocess.rst:942: # ==> Perhaps ``# becomes`` or something like that would be better here. http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.r… File Doc/reference/simple_stmts.rst (right): http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.r… Doc/reference/simple_stmts.rst:334: if not expression: raise AssertionError if not expression: raise AssertionError http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.r… Doc/reference/simple_stmts.rst:339: if not expression1: raise AssertionError(expression2) if not expression1: raise AssertionError(expression2) http://bugs.python.org/review/23921/

1 0

Document magic methods called by built-in functions (issue 10289)
by vadmium+py＠gmail.com April 12, 2015

April 12, 2015

https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst File Doc/library/functions.rst (right): https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst#n… Doc/library/functions.rst:1289: The items in *iterable* need to be orderable; otherwise, :exc:`TypeError` is Actually I think they need to be totally orderable, though TypeError isn’t going to be raised for partially orderable sequences. https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst#n… Doc/library/functions.rst:1291: by defining :dfn:`rich comparison methods` like :meth:`__lt__`, described in Would be good to be more specific. I suspect it is sufficient to define the < and > operations, by defining at least one of __lt__() and __gt__(). And I suspect that many other comparison operations, <=, >=, ==, !=, __eq__(), __le__(), etc, are never used. See also the list.sort() specification. https://bugs.python.org/review/10289/

1 0

[issue23904] pathlib.PurePath does not accept bytes components
by Bruno Cauet April 11, 2015

April 11, 2015

New submission from Bruno Cauet: At https://docs.python.org/3/library/pathlib.html#pure-paths one can read > Each element of pathsegments can be either a string or bytes object representing a path segment; it can also be another path object: which is a lie: >>> pathlib.PurePath(b"/foo") Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/bru/code/cpython/Lib/pathlib.py", line 609, in __new__ return cls._from_parts(args) File "/home/bru/code/cpython/Lib/pathlib.py", line 638, in _from_parts drv, root, parts = self._parse_args(args) File "/home/bru/code/cpython/Lib/pathlib.py", line 630, in _parse_args % type(a)) TypeError: argument should be a path or str object, not <class 'bytes'> So either (1) the doc is wrong (2) PathLib path management fails: it should decode bytes parts with os.fsdecode() I doubt I tagged both components. I'll be happy to provide a fix once you decide what is the right solution. I take this opportunity to share an itch: filesystem encoding on Unix cannot be reliably determined. sys.getfilesystemencoding() is only a preference and there is no guarantee that an arbitrary file will respect it. This is extensively discussed in the following thread: https://mail.python.org/pipermail/python-dev/2014-August/135873.html What is the right way to deal with those? If I use "surrogateescape" (see PEP383) how can I display the fake-unicode path to the user? `print()` does seems to use strict encoding. Should I encode it with "surrogateescape" or "ignore" myself beforehand? ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 240414 nosy: bru, docs@python priority: normal severity: normal status: open title: pathlib.PurePath does not accept bytes components versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23904> _______________________________________

3 3