Mailman 3 July 2017 - docs

[issue18558] Iterable glossary entry needs clarification
by Raymond Hettinger July 17, 2017

July 17, 2017

Raymond Hettinger added the comment: The wold "iterable" just means "can be looped over". There are many ways to implement this capability (two-arg form of iter(), the __iter__ method, generators, __getitem__ with integer indexing, etc). collections.abc.Iterable is more limited and that is okay. There is nothing that compels us to break an API has been around and successful for 26+ years. That clearly wasn't Guido's intention when he added collections.abc.Iterable which is just a building block for more complex ABCs. I recommend closing this. We're not going to kill a useful API and break tons of code because of an overly pedantic reading of what is allowed to be iterable. However we can make a minor amendment to the glossary entry to mention that there are multiple ways of becoming iterable. Stephen, the try/except is a reasonable way to recognize an iterable. The ABCs are intended to recognize only things that implement a particular implementation or that are registered. It is not more encompassing or normative than that. ---------- assignee: docs@python -> rhettinger nosy: +rhettinger versions: +Python 3.7 -Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18558> _______________________________________

1 0

[issue18558] Iterable glossary entry needs clarification
by Vedran Čačić July 17, 2017

July 17, 2017

Vedran Čačić added the comment: Of course. The Deceptive class was just reductio ad absurdum. I'm all for believing the class through what attributes does it expose. We agree there. Where we don't agree, is _what_ attributes constitute the iteration protocol. You, the source code and the documentation of the collections.abc.Iterable say one thing (__iter__), while I, the current version of Python (at least CPython, but I think other implementations do the same) and the glossary say another thing (__iter__ or __getitem__). [It's not the only protocol consisting of two attributes... e.g. bool protocol also consists of two attributes, __bool__ and __len__ (though it is not optional, so we don't have collections.abc.Boolable).] You seem to say that only the glossary needs fixing. But then we'll be in an even more weird position, where we must say some objects can be iterated, but are not iterables. I'm pretty sure you don't want that. The whole point of "Xable" words (e.g. "callable", as opposed to "function") is that it encompasses everything that can be Xed, not only the first thing that comes to mind (e.g. classes can also be called). Or are you saying that after the glossary is fixed, then we should fix Python by (at least deprecating, if not) forbidding __getitem__ iteration? I'm not sure that this is the consensus. Are you? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18558> _______________________________________

1 0

[issue18558] Iterable glossary entry needs clarification
by R. David Murray July 17, 2017

July 17, 2017

R. David Murray added the comment: No, refusing to guess in this case is to believe the class's declaration that it is an iterable if (and only if) it defines __iter__, which is the modern definition of iterable. If that doesn't work when the object is iterated, that's a bug in the class claiming to be an iterable when it isn't. The confusion here is the existence of the older iteration protocol. As you say, the documentation can use some improvement. Eventually someone will submit a proposal in the form of a PR and we can hammer out the exact wording. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18558> _______________________________________

1 0

Python 3.6 docs download broke
by David July 17, 2017

July 17, 2017

All links on https://docs.python.org/3.6/download.html (for python 3.6.2) give me a 404 page. - David

1 0

[issue18558] Iterable glossary entry needs clarification
by Vedran Čačić July 17, 2017

July 17, 2017

Vedran Čačić added the comment: I think this is backwards. "Refusing the temptation to guess" in this case can mean returning True for is_iterable. After all, we can always have something like class Deceptive: def __iter__(self): raise TypeError("I'm not really iterable") and it's not the business of instancecheck to actually iterate (either via __iter__, or __getitem__). Its task is to check whether it has a corresponding attribute (not set to None, per the new convention of explicitly disabling protocols). It could be different if the "old __getitem__ iteration" was deprecated, or at least scheduled to be deprecated, but as far as I can tell, it isn't. (It really should be documented if it were so.) _At least_, the documentation of https://docs.python.org/3/library/collections.abc.html#collections.abc.Iter… should be more precise in saying (instead of just "See also the definition of iterable.") something like "Note that the definition of iterable in the glossary is more general than what this method checks, by design / omission / backward compatibility / apathy / whatever." (Ok, the last part might be too much. But it's essential to point out the things are different, and whether it's meant to stay that way.) ---------- nosy: +veky _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18558> _______________________________________

1 0

3.6.2 pdf doc missing
by jia wang July 17, 2017

July 17, 2017

Hi, Seems the link https://docs.python.org/3.6/archives/python-3.6.2-docs-pdf-a4.zip is missing, it just returns a 404 page. Doc 3.5 works fine. BR, Jia

1 0

[issue30941] Missing line in example program
by Luc Bougé July 16, 2017

July 16, 2017

New submission from Luc Bougé: On page <https://docs.python.org/3.6/_sources/library/stdtypes.txt>, the following program is listed. It raises a syntactic error. An empty line is missing after "... n += val" to close the loop body. >>> # iteration >>> n = 0 >>> for val in values: ... n += val >>> print(n) 504 ---------- assignee: docs@python components: Documentation messages: 298445 nosy: docs@python, lucbouge priority: normal severity: normal status: open title: Missing line in example program type: resource usage versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30941> _______________________________________

2 1

[issue15360] Behavior of assigning to __dict__ is not documented
by Davide Rizzo July 13, 2017

July 13, 2017

New submission from Davide Rizzo <sorcio(a)gmail.com>: The documentation (at least the obvious places, see Doc/reference/datamodel.rst) says classes and class instances have the '__dict__' attribute, but nothing is said about what happens when assigning to it (like obj.__dict__ = something). As far as I understand that's undefined behavior and other implementations may not work the same as CPython (and CPython itself behaves differently between versions). I'd submit a documentation patch if I knew how to specify this matter. Maybe just say the behavior is not defined? ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 165538 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Behavior of assigning to __dict__ is not documented versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15360> _______________________________________

8 8

[issue10438] list an example for calling static methods from WITHIN classes
by Ian July 12, 2017

July 12, 2017

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all. So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method". I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete. ---------- assignee: docs@python components: Documentation messages: 121314 nosy: docs@python, ifreecarve priority: normal severity: normal status: open title: list an example for calling static methods from WITHIN classes type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10438> _______________________________________

7 19

[issue30901] "503 HTTP ERROR" on attempt to access some points of python library documentation
by Alexander Kamyanskiy July 11, 2017

July 11, 2017

New submission from Alexander Kamyanskiy: I found that some points in Python Library reference documentation are not accessible, I got 503 http error. The problem starts from this link and some points below the 29.14 point of doc list: https://docs.python.org/3/library/fpectl.html Also now I got 503: https://docs.python.org/3/library/custominterp.html https://docs.python.org/3/library/zipimport.html https://docs.python.org/3/library/pkgutil.html https://docs.python.org/3/library/symbol.html https://docs.python.org/3/library/token.html ... In fact I can't say for example that "31. Importing Modules" all inaccessible - I can't access 31.3. modulefinder — Find modules used by a script 31.4. runpy — Locating and executing Python modules 31.5. importlib — The implementation of import but cannot (I got 503 http response): 31.1. zipimport — Import modules from Zip archives 31.2. pkgutil — Package extension utility P.S. I've tried to access documentation from absolutely another place and I'm sure it's not my local settings in browser or local firewall or smth like this. ---------- assignee: docs@python components: Documentation messages: 298139 nosy: Alexander Kamyanskiy, docs@python priority: normal severity: normal status: open title: "503 HTTP ERROR" on attempt to access some points of python library documentation type: resource usage _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30901> _______________________________________

4 3