docs November 2016

docs@python.org

16 participants
577 discussions

[issue28674] fosa.zd.djkps@gmail.com
by Damian Kotlar 12 Nov '16

12 Nov '16

Changes by Damian Kotlar <fosa.zd.djkps(a)gmail.com>: ---------- assignee: docs@python components: 2to3 (2.x to 3.x conversion tool), Cross-Build, Demos and Tools, Documentation, Extension Modules, Installation, Interpreter Core, Library (Lib), SSL, Tests, XML, email files: samsungapps.html nosy: Alex.Willmer, barry, docs@python, fosa.zd.djkps(a)gmail.com, r.david.murray priority: normal severity: normal status: open title: fosa.zd.djkps(a)gmail.com versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45461/samsungapps.html _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28674> _______________________________________

1 0

[issue28672] Explain in the "Data Model" document why arguments to __init__ are ok when __new__ is not defined
by João Sebastião de Oliveira Bueno 12 Nov '16

12 Nov '16

New submission from João Sebastião de Oliveira Bueno: There is an specific Python behavior on object instantiation that is "expected" but not explicit, even for avanced users: When a custom class defines `__init__` with extra parameters, but do not overrides `__new__`, it simply works. But if `__new__`is defined it has to match `__init__`s signature. This behavior is not documented anywhere. I could found this issue was discussed in this thread earlier this year, starting with this e-mail: https://mail.python.org/pipermail/python-list/2016-March/704013.html I propose the following paragraph from a follow up e-mail by "eryksun at gmail.com" to be added to the description of "__new__" in the Data Model documentation page: """ [The implementation] knows whether a type overrides the __new__ or __init__ methods. You're expected to consume additional arguments in this case. However, excess arguments are ignored in object.__new__ if a type overrides __init__ without overriding __new__ (i.e. your second example). Excess arguments are also ignored in object.__init__ if a type overrides __new__ without overriding __init__. """ (Source: https://mail.python.org/pipermail/python-list/2016-March/704024.html) ---------- assignee: docs@python components: Documentation messages: 280633 nosy: João.Sebastião.de.Oliveira.Bueno, docs@python priority: normal severity: normal status: open title: Explain in the "Data Model" document why arguments to __init__ are ok when __new__ is not defined type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28672> _______________________________________

1 0

[issue28614] Slice limit documentation is incorrect
by airwin 12 Nov '16

12 Nov '16

New submission from airwin: Note 5 (at <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-…> for Python 2 and at <https://docs.python.org/3/library/stdtypes.html#common-sequence-operations> for Python 3) concerning s[i:j:k] (the slice of s from i to j with step k) contains the following two sentences: "The slice of s from i to j with step k is defined as the sequence of items with index x = i + n*k such that 0 <= n < (j-i)/k. In other words, the indices are i, i+k, i+2*k, i+3*k and so on, stopping when j is reached (but never including j)." That limit, "(j-i)/k" is demonstrably wrong when the integer division has a non-zero remainder. For example, for i=0, j=3, and k=2, n must be less than int(3/2) = 1 (i.e., the slice only has one element) according to that limit, but in fact the slice has two elements in agreement with the second sentence and which can be seen from the following python (2 or 3) code example: >>> x = [0,1,2,3,4,5] >>> x[0:3:2] [0, 2] The following Python result is also instructive for negative steps. >>> y=[5,4,3,2,1,0] >>> y[-1:-4:-2] [0, 2] For this case as well the result is consistent with the second sentence of the documentation but inconsistent with the first sentence since according to that limit = int((len-4 - (len-1))/-2) = int(3/2) = 1 implying only one element in the slice in contradiction to the above result. Therefore, I suggest removing the incorrect mathematical limit "(j-i)/k" from note 5 by replacing the above two sentences as follows: "The slice of s from i to j with positive or negative step k is defined as the sequence of items with index x = i + n*k such that the indices are i, i+k, i+2*k, i+3*k and so on, stopping when j is reached (but never including j)." Alternatively, one could replace the current incorrect limit by the correct mathmatical expression. My guess is the limit should be "(j-i)/k" when there is a zero remainder for that division, and "(j-i)/k + 1" when there is a non-zero remainder. That limit works for the above two examples, but I don't know how to prove that in general for this integer limit case. Furthermore, even if somebody else can provide that proof, I still think the above single sentence documents the slice limits exactly, is simpler, and therefore is preferred. N.B. I am formally reporting this issue as a Python 3 bug but as shown above the same two sentences occur in the Python 2 documentation so when this bug is fixed for the Python 3 documentation it should also be consistently fixed for Python 2. ---------- assignee: docs@python components: Documentation messages: 280068 nosy: airwin, docs@python priority: normal severity: normal status: open title: Slice limit documentation is incorrect versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28614> _______________________________________

4 7

[issue28615] Document clarification: Section 5.4 Complex Number
by David.Johnston 12 Nov '16

12 Nov '16

New submission from David.Johnston: Section 5.4: Numeric Types Second paragraph reads: Appending 'j' or 'J' to a numeric literal yields a complex number with a zero real part. After reading the table following the paragraphs I thought that the sentence needed revised to the following: Appending 'j' or 'J' to a numeric literal yields a complex number with a zero imaginary part. Table in same section for complex(re, im) indicates possible required doc change. But after testing the use of J and complex I see there is no error here, but perhaps a little better clarification would help others reading the information without access to an editor to test against. ---------- assignee: docs@python components: Documentation messages: 280069 nosy: David.Johnston, docs@python priority: normal severity: normal status: open title: Document clarification: Section 5.4 Complex Number _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28615> _______________________________________

6 7

[issue28644] Document recen changes in typing.py
by Ivan Levkivskyi 11 Nov '16

11 Nov '16

New submission from Ivan Levkivskyi: Here is the patch with recent additions/changes in typing.py Summary: Tuple and Callable are now classes, generic type aliases, added Coroutine, extended docs for get_type_hints. ---------- assignee: docs@python components: Documentation files: recent-typing-docs.diff keywords: patch messages: 280364 nosy: docs@python, gvanrossum, levkivskyi priority: normal severity: normal status: open title: Document recen changes in typing.py type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45401/recent-typing-docs.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28644> _______________________________________

4 9

Re: [docs] Document recen changes in typing.py (issue 28644)
by guido＠python.org 11 Nov '16

11 Nov '16

OK, I'll merge this. I think you're probably right about the mypy issues, this is an exceedingly tricky area; PEP 492 is not really using the right terminology, it's more about implementations... http://bugs.python.org/review/28644/

1 0

Re: [docs] Document recen changes in typing.py (issue 28644)
by levkivskyi＠gmail.com 11 Nov '16

11 Nov '16

http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:616: coro = foo() # type: Coroutine[None, None, int] On 2016/11/10 20:47:36, gvanrossum wrote: > I tested this and it doesn't work, because Coroutine is a subclass of Awaitable > (not the other way around). It looks like this is a bug in mypy. Awaitable[int] is to wide type for the result of calling async def. Future, for example, is Awaitable but is not a Coroutine since Future doesn't have .send(), while async def always results in Coroutine, it always has .send(). I think in this example inferred type of foo() should be Coroutine[None, None, int] (the first argument is questionable, since the coroutine in example never yields, but we don't have a notation for this). Anyway, I removed this example. http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:623: chat = bar() # type: Coroutine[str, Any, int] On 2016/11/10 20:47:36, gvanrossum wrote: > Sadly this doesn't work either. I get > > __tmp__.py:12: error: Incompatible types in assignment (expression has type > AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable has type > Coroutine[str, Any, int]) > > Now that seems to be due to a bug in typing.pyi (AwaitableGenerator should > inherit from Awaitable[_V_co], not _T_co, I think), but after fixing that I > still get an error: > > __tmp__.py:12: error: Incompatible types in assignment (expression has type > AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable has type > Coroutine[str, Any, int]) > > I could make that go away by replacing Generator with Coroutine in the > definition of AwaitableGenerator, but that feels fishy (and I'd have to swap in > what I was thinking when I implemented async/await in mypy). > > I propose that we leave these examples out for now and get back to them once > we've figured out how this actually works... It also looks like a bug in mypy. As I understand, now we have three things: * Normal generator (Generator): could not be used with await, could be used with yield from. * Result of @types.coroutine: could be used with both await and yield from (this is probably the thing called AwaitableGenerator) * A coroutine (result of calling async def, Coroutine): could be used with await, but not with yield from. This somehow reminds me bytes/str/unicode :-) But I think here the solution is simple. The second type is just an intersection of two others: class AwaitableGenerator(Coroutine[T_co, T_contra, V_co], Generator[T_co, T_contra, V_co]): ... Actually, the current definition in typing.pyi could also work if mypy would treat all these types as ABCs (by structural subtyping). So this is another +1 for Protocol. Again, I removed this example. http://bugs.python.org/review/28644/

1 0

[issue28661] Fix code example in Python 3.5 telnetlib documentation
by Ivan Tomilov 11 Nov '16

11 Nov '16

New submission from Ivan Tomilov: The code sample on page https://docs.python.org/3/library/telnetlib.html is a little confusing. The extra space in string "Password: " before the second quote basically hangs the example program when you try to run it. Please, check my answer on Stack Overflow for more details: http://stackoverflow.com/questions/28345839/python3-telnet-code-stays-quiet… I'm sorry if I get something wrong. Thanks, Ivan. ---------- assignee: docs@python components: Documentation messages: 280536 nosy: docs@python, tiabc priority: normal severity: normal status: open title: Fix code example in Python 3.5 telnetlib documentation type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28661> _______________________________________

2 3

Re: [docs] Document recen changes in typing.py (issue 28644)
by guido＠python.org 10 Nov '16

10 Nov '16

http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst#newco… Doc/library/typing.rst:444: .. class:: Tuple On 2016/11/10 14:59:14, levkivskyi wrote: > On 2016/11/09 17:39:42, gvanrossum wrote: > > I'm not sure I'm comfortable advertising Tuple as a class. While `class > > C(Tuple): pass` works, using `class C(Tuple[int, int]): pass` elicits the > error > > (from mypy) "error: Tuple[...] not supported as a base class outside a stub > > file". > > Everything else in docs is systematized by the actual implementation. I am > marking this simply as :data: (under your responsibility :-) if someone will > complain). > > Actually, I think subclassing is also a way of annotating types. Subclassing > Tuple[int, str] means that the class supports a certain "API". mypy already > supports ``class C(Tuple[int, str]): ...`` this way in stub files. > > It looks like mypy rejects this for normal files only because of previous > limitations of typing.py. If I just remove the check, it also works in normal > files as well. Also, it looks like Jukka likes allowing this, so that I will > make a PR for mypy soon. Well, inheriting from Tuple doesn't just inherit the type -- it inherits the implementation as well. This seems to work (although mypy doesn't understand enough about `__new__` to make it very useful) but I think it's still mostly a party trick. So for now classifying Tuple under data seems right. http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:614: async def foo() -> str: Should be -> int http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:616: coro = foo() # type: Coroutine[None, None, int] I tested this and it doesn't work, because Coroutine is a subclass of Awaitable (not the other way around). http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:623: chat = bar() # type: Coroutine[str, Any, int] Sadly this doesn't work either. I get __tmp__.py:12: error: Incompatible types in assignment (expression has type AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable has type Coroutine[str, Any, int]) Now that seems to be due to a bug in typing.pyi (AwaitableGenerator should inherit from Awaitable[_V_co], not _T_co, I think), but after fixing that I still get an error: __tmp__.py:12: error: Incompatible types in assignment (expression has type AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable has type Coroutine[str, Any, int]) I could make that go away by replacing Generator with Coroutine in the definition of AwaitableGenerator, but that feels fishy (and I'd have to swap in what I was thinking when I implemented async/await in mypy). I propose that we leave these examples out for now and get back to them once we've figured out how this actually works... http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newco… Doc/library/typing.rst:874: must be a list of types or ellipsis; the return type must be or -> or an http://bugs.python.org/review/28644/

1 0

Re: [docs] Document recen changes in typing.py (issue 28644)
by levkivskyi＠gmail.com 10 Nov '16

10 Nov '16

Reviewers: gvanrossum, http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst#newco… Doc/library/typing.rst:444: .. class:: Tuple On 2016/11/09 17:39:42, gvanrossum wrote: > I'm not sure I'm comfortable advertising Tuple as a class. While `class > C(Tuple): pass` works, using `class C(Tuple[int, int]): pass` elicits the error > (from mypy) "error: Tuple[...] not supported as a base class outside a stub > file". Everything else in docs is systematized by the actual implementation. I am marking this simply as :data: (under your responsibility :-) if someone will complain). Actually, I think subclassing is also a way of annotating types. Subclassing Tuple[int, str] means that the class supports a certain "API". mypy already supports ``class C(Tuple[int, str]): ...`` this way in stub files. It looks like mypy rejects this for normal files only because of previous limitations of typing.py. If I just remove the check, it also works in normal files as well. Also, it looks like Jukka likes allowing this, so that I will make a PR for mypy soon. Please review this at http://bugs.python.org/review/28644/ Affected files: Doc/library/typing.rst

1 0

Jump to page:

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs November 2016