Mailman 3 July 2016 - docs

Re: [docs] Expand documentation about type aliases and NewType in the typing module (issue 27644)
by guido＠python.org July 29, 2016

July 29, 2016

LGTM. I will merge this. http://bugs.python.org/review/27644/diff/18014/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/27644/diff/18014/Doc/library/typing.rst#newco… Doc/library/typing.rst:103: is not possible to create another ``NewType`` based on a ``Derived`` type:: On 2016/07/29 23:23:20, levkivskyi wrote: > I don't think we need to mention this limitation. It might be useful to further > derive the type returned by NewType. The PEP says that Base must be a proper > class, but I could imagine that this limitation will be relaxed slightly to > allow also unique types returned by NewType. > > However, if it is OK with Guido, then it is also OK with me. The limitation is very real. I really don't want people to start creating NewTypes with another NewType as base. I probably didn't think about this when reviewing the PEP text, so perhaps the PEP should also be updated. http://bugs.python.org/review/27644/

1 0

Re: [docs] Expand documentation about type aliases and NewType in the typing module (issue 27644)
by levkivskyi＠gmail.com July 29, 2016

July 29, 2016

I have only one optional comment. http://bugs.python.org/review/27644/diff/18014/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/27644/diff/18014/Doc/library/typing.rst#newco… Doc/library/typing.rst:103: is not possible to create another ``NewType`` based on a ``Derived`` type:: I don't think we need to mention this limitation. It might be useful to further derive the type returned by NewType. The PEP says that Base must be a proper class, but I could imagine that this limitation will be relaxed slightly to allow also unique types returned by NewType. However, if it is OK with Guido, then it is also OK with me. http://bugs.python.org/review/27644/

1 0

[issue27624] unclear documentation on Queue.qsize()
by Doug Hoskisson July 29, 2016

July 29, 2016

New submission from Doug Hoskisson: The documentation for Queue.qsize(): "Return the approximate size of the queue." "approximate" is unclear. It might suggest some strategy used for approximating, or it might be the exact size at an arbitrary time. It should be made more clear. ---------- assignee: docs@python components: Documentation messages: 271362 nosy: Doug Hoskisson, docs@python priority: normal severity: normal status: open title: unclear documentation on Queue.qsize() versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27624> _______________________________________

4 16

Typo in Windows Install Instructions
by Jack Copper July 29, 2016

July 29, 2016

While I noticed a typo, I am greatly impressed with the clarity and completeness of the Windows installation instructions. Thanks! The typo: Page (as shown in IE 11 address bar): https://docs.python.org/3/using/windows.html "pace" should be "page" *The Python Launcher for Windows will be installed according to the option at the bottom of the first pace Cheers, Jack ____________________________ Jack Copper Managing Director NeuralStudio SEZC #68 West Bay Road, Bay Town Plaza PO Box 10315 Grand Cayman KY1-1003 Cayman Islands Direct: +1 (345) 815-3930 Mobile: +1 (345) 925-8459 SKYPE: jack-copper ____________________________ This communication is for use by the intended recipient(s) only and contains information that may be privileged, confidential or copyrighted under applicable law. If you are not an intended recipient, you are hereby formally notified that any use, copying or distribution of this e-mail, in whole or in part, is strictly prohibited. Please notify the sender by return e-mail and delete this e-mail from your system. This e-mail does not constitute a consent to the use of sender's contact information for direct marketing purposes or for transfers of data to third parties. **************************************************************************

2 1

Re: [docs] Expand documentation about type aliases and NewType in the typing module (issue 27644)
by michael.lee.0x2a＠gmail.com July 28, 2016

July 28, 2016

Reviewers: gvanrossum, levkivskyi, http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:65: The static type checker will treat the new type almost as if it were a subclass On 2016/07/29 00:11:37, levkivskyi wrote: > It is not clear why do you need word "almost" here. > NewType creates something that type checker treats as equivalent of a subclass > with only one constructor that accepts an instance of the base class. I used the word "almost" mainly because the created type doesn't behave exactly like a subclass in all cases -- the main difference is that you're not allowed to subclass the derived type. So, this fails: from typing import NewType UserId = NewType('UserId', int) # Throws an exception at runtime; mypy explicitly flags this as an error class Foo(UserId): pass So I guess it might be more accurate to say that NewType creates something that behaves like a final subclass, in Java terms? Should I edit the patch to include a sentence or two describing this distinction, just remove the word "almost", or do something else? Please review this at http://bugs.python.org/review/27644/ Affected files: Doc/library/typing.rst diff -r da9898e7e90d -r c5151efd2bca Doc/library/typing.rst --- a/Doc/library/typing.rst Wed Jul 27 16:59:22 2016 +0200 +++ b/Doc/library/typing.rst Thu Jul 28 10:12:22 2016 -0700 @@ -29,10 +29,77 @@ Type aliases ------------ -A type alias is defined by assigning the type to the alias:: +A type alias is defined by assigning the type to the alias. In this example, +``Vector`` and ``List[float]`` will be treated as interchangeable synonyms:: + from typing import List Vector = List[float] +Type aliases are useful for simplifying complex type signatures. For example:: + + from typing import Dict, Tuple, List + + + ConnectionOptions = Dict[str, str] + Address = Tuple[str, int] + Server = Tuple[Address, ConnectionOptions] + + def broadcast_message(message: str, servers: List[Server]) -> None: + ... + + # The static type checker will treat the previous type signature as + # being exactly equivalent to this one. + def broadcast_message(message: str, servers: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: + ... + +NewType +------- + +Use the ``NewType`` helper function to create distinct types:: + + from typing import NewType + + UserId = NewType('UserId', int) + some_id = UserId(524313) + +The static type checker will treat the new type almost as if it were a subclass +of the original type. This is useful in helping catch logical errors:: + + def get_user_name(user_id: UserId) -> str: + ... + + user_a = get_user_name(UserId(42351)) # typechecks + user_b = get_user_name(-1) # does not typecheck; an int is not a UserId + +You may still perform all ``int`` operations on a variable of type ``UserId``, but the +result will always be of type ``int``. This lets you pass in a ``UserId`` wherever an +``int`` might be expected, but will prevent you from accidentally creating a ``UserId`` +in an invalid way:: + + output = UserId(23413) + UserId(54341) # `output` is of type `int`, not `UserId` + +Note that these checks are enforced only by the static type checker. At runtime the statement +``Derived = NewType('Derived', Base)`` will make ``Derived`` a function that immediately +returns whatever parameter you pass it. That means the expression ``Derived(some_value)`` +does not create a new class or introduce any overhead beyond that of a regular function call. + +More precisely, the expression ``some_value == Derived(some_value)`` is always true at runtime. + +See :pep:`484` for more details. + +.. note:: + + Recall that type aliases declares two types to be *equivalent* to one another. + Doing ``Alias = Original`` will make the static type checker treat ``Alias`` as being + *exactly equivalent* to ``Original`` in all cases. This is useful when you want to simplify + complex type signatures. + + In contrast, ``NewType`` declares one type to be a *derivative* of another. + Doing ``Derived = NewType('Derived', Original)`` will make the static type checker + treat ``Derived`` as a *subclass* of ``Original``, which means a value of type + ``Original`` cannot be used in places where a value of type ``Derived`` is expected. + This is useful when you want to prevent logic errors with minimal runtime cost. + Callable --------

1 0

Re: [docs] Expand documentation about type aliases and NewType in the typing module (issue 27644)
by levkivskyi＠gmail.com July 28, 2016

July 28, 2016

I would add two small comments http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:65: The static type checker will treat the new type almost as if it were a subclass It is not clear why do you need word "almost" here. NewType creates something that type checker treats as equivalent of a subclass with only one constructor that accepts an instance of the base class. http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:86: More precisely, the expression ``some_value == Derived(some_value)`` is always true at runtime. I would replace here ``some_value == Derived(some_value)`` with ``some_value is Derived(some_value)`` http://bugs.python.org/review/27644/

1 0

Expand documentation about type aliases and NewType in the typing module (issue 27644)
by guido＠python.org July 28, 2016

July 28, 2016

Great! A few nits. http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:32: A type alias is defined by assigning the type to the alias. In this example, Can you try to make all lines you've added shorter than 80 chars? Even the examples (examples with long lines cause annoying horizontal scroll bars). http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:36: Vector = List[float] I'd add an example that passes a List[float] into a function expecting a Vector. E.g. def sum(a: Vector): ... sum([0.0, 1.1, 2.2]) http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:92: Recall that type aliases declares two types to be *equivalent* to one another. "type aliases declares" -- plural subject with singular verb. Maybe "the use of a type alias causes two types ..." ? http://bugs.python.org/review/27644/diff/18004/Doc/library/typing.rst#newco… Doc/library/typing.rst:97: In contrast, ``NewType`` declares one type to be a *derivative* of another. derivative -> subtype http://bugs.python.org/review/27644/

1 0

Broken links
by Luca Sigfrido Percich July 28, 2016

July 28, 2016

Hi, the following links from https://docs.python.org/3.4/download.html are broken: https://docs.python.org/3.4/archives/python-3.4.5-docs-pdf-letter.tar.bz2 https://docs.python.org/3.4/archives/python-3.4.5-docs-pdf-a4.tar.bz2 https://docs.python.org/3.4/archives/python-3.4.5-docs-text.tar.bz2 https://docs.python.org/3.4/archives/python-3.4.5-docs.epub Best regards Sig

1 0

Re: [docs] Patch to enhance literal block language declaration (issue 26462)
by vadmium+py＠gmail.com July 28, 2016

July 28, 2016

https://bugs.python.org/review/26462/diff/17976/Doc/whatsnew/3.2.rst File Doc/whatsnew/3.2.rst (right): https://bugs.python.org/review/26462/diff/17976/Doc/whatsnew/3.2.rst#newcod… Doc/whatsnew/3.2.rst:487: $ python -q Lets leave this as you had it before; it is demonstrating the -q option https://bugs.python.org/review/26462/

1 0

[issue27626] Spelling fixes
by Emanuel Barry July 28, 2016

July 28, 2016

New submission from Emanuel Barry: LGTM. ---------- nosy: +ebarry stage: patch review -> commit review _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27626> _______________________________________

6 7