README.md: rearrange first paragraph to be more friendly #4002

elazarg · 2017-09-25T06:19:39Z

The discussion of different annotations need not be the first thing the reader see.

obestwalter · 2017-09-25T09:22:12Z

README.md

@@ -56,6 +47,17 @@ def fib(n: int) -> Iterator[int]:
 Mypy is in development; some features are missing and there are bugs.
 See 'Development status' below.

+Annotations


Good move 🚜

gvanrossum · 2017-09-25T19:03:00Z

Can you move the bullet about the xml reporter elsewhere? It's a distraction at this point. I'd also fold the discussion of supported Python 3 versions into one sentence.

elazarg · 2017-09-25T19:49:16Z

I tried something slightly different - demonstration for python 2 too. I'm not sure this is a good idea, but I couldn't find the right way to phrase it.

gvanrossum

I'm not keen on explicit annotations for local variables, since these are correctly inferred from the initializer. Rest LG.

emmatyping · 2017-09-25T19:55:06Z

README.md

@@ -160,7 +168,8 @@ In Windows, the script is generally installed in
    C:\>\Python34\python \Python34\Scripts\mypy PROGRAM

 If you are on Windows using Python 3.3 or 3.4, and would like to use XML reports
-download LXML from [PyPi](https://pypi.python.org/pypi/lxml).
+download LXML from [PyPi](https://pypi.python.org/pypi/lxml). 
+XML based reports do not work on Python 3.3 and 3.4 on Windows.


They do work, but only if you have LXML installed. The last sentence can be deleted.

elazarg · 2017-09-25T20:03:16Z

So should I just remove the annotations? I think it's valuable to be aware of the way to annotate variables, since most people will not read the PEP. If the example will return a list we'll have both:

from typing import List 

def fib(n: int) -> List[int]:
    a, b = 0, 1
    result: List[int] = []
    while a < n:
        result.append(a)
        a, b = b, a + b
    return result

ilevkivskyi · 2017-09-25T20:09:14Z

@elazarg

I think it's valuable to be aware of the way to annotate variables, since most people will not read the PEP.

I am not sure here, people will most likely not read read the PEP, but we should make them read the docs (at least to some extent).

gvanrossum · 2017-09-25T20:11:46Z

The readme is not the place for this. It should point people to the real docs, in particular an introduction, right after the example.

…

On Sep 25, 2017 1:03 PM, "Elazar Gershuni" ***@***.***> wrote: So should I just remove the annotations? I think it's valuable to be aware of the way to annotate variables, since most people will not read the PEP. If the example will return a list we'll have both: from typing import List def fib(n: int) -> List[int]: a, b = 0, 1 result: List[int] = [] while a < n: result.append(a) a, b = b, a + b return result — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#4002 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACwrMvSLCZYEsucXPc9fqi0HZLOvEL3_ks5smAcIgaJpZM4PiP6n> .

Smaller example for python2; only show the difference

emmatyping · 2017-09-25T21:08:02Z

README.md

@@ -168,8 +168,7 @@ In Windows, the script is generally installed in
    C:\>\Python34\python \Python34\Scripts\mypy PROGRAM

 If you are on Windows using Python 3.3 or 3.4, and would like to use XML reports


If #4007 gets merged before this, this sentence can be removed, as there are wheels for all Python versions on Windows now, and installing via test-requirements will "just work".

elazarg · 2017-09-26T20:35:24Z

Is this OK now? I tried to make it shorter so the first part will fit in a laptop screen.

gvanrossum

Sorry, I had pending comments that I forgot to send.

gvanrossum · 2017-09-25T22:38:17Z

README.md

+
+For Python 2.7, the standard annotations are written as comments:
+```python
+def reverse(s):  # type: str -> str


Please put the # type comment on a separate line (it's the more common style).

gvanrossum · 2017-09-25T22:40:15Z

README.md

+    return s[::-1]
+```
+
+See [the documentation](http://mypy.readthedocs.io/en/stable/introduction.html) for more examples.


I think the docs link should come before the Python 2 example. There should be a separate deep link for the Python 2 docs. The PEP 484 link should be moved back into the "What is mypy" section above (but without mention of Python 3.5).

I'm not sure how to keep it fluent, while staying clear and concise. I gave it another try.

Maybe there can be some explanation about PEP-484 in a dedicated section.

@ethanhs

as per @ethanhs comment

ilevkivskyi · 2017-09-26T21:10:04Z

README.md

+For Python 2.7, the standard annotations are written as comments:
+```python
+def reverse(s):
+    # type: str -> str


This should be # type: (str) -> str (note parentheses), otherwise it is syntax error in type comment.

ilevkivskyi · 2017-09-26T21:11:05Z

README.md

-
-For Python 2.7, you can add annotations as comments (this is also
-specified in [PEP 484](https://www.python.org/dev/peps/pep-0484/)).
+hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) to your Python programs, and use mypy to type check them statically.


Not super-important, but could you please make lines in your diff 79 chars?

Sorry. I will try to keep it in mind.

ilevkivskyi · 2017-09-26T21:14:00Z

README.md

+```python
+def reverse(s):
+    # type: str -> str
+    return s[::-1]


Maybe use a slightly less trivial example? Like is_palindrome(s) that returns s == s[::-1]?

Nice! :)
I tried to find something like that and all I came up with was reverse :(

oops

gvanrossum

I'll merge it now.

README.md: rearrange first paragraph to be more friendly

77938e0

obestwalter reviewed Sep 25, 2017

View reviewed changes

Demonstration for comments and new style annotations

43f3988

gvanrossum requested changes Sep 25, 2017

View reviewed changes

emmatyping reviewed Sep 25, 2017

View reviewed changes

Remove erroneous statement

998e4c3

Remove variable annotations. Change description of annotations

932aa4d

Smaller example for python2; only show the difference

emmatyping reviewed Sep 25, 2017

View reviewed changes

gvanrossum mentioned this pull request Sep 25, 2017

Release 0.530 planning #4009

Closed

5 tasks

gvanrossum requested changes Sep 26, 2017

View reviewed changes

elazarg added 2 commits September 27, 2017 00:06

move PEP-484 link and type comment; deep link for Python 2

5422d17

Remove mention of LXML

8ed7f76

as per @ethanhs comment

ilevkivskyi reviewed Sep 26, 2017

View reviewed changes

elazarg and others added 3 commits September 27, 2017 00:16

Fix type comment and give better example

db8e6df

s/str/bool/

e2b9b94

oops

Wrap long line.

09c1055

gvanrossum approved these changes Sep 26, 2017

View reviewed changes

gvanrossum merged commit 6c66117 into python:master Sep 26, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md: rearrange first paragraph to be more friendly #4002

README.md: rearrange first paragraph to be more friendly #4002

elazarg commented Sep 25, 2017

obestwalter Sep 25, 2017

gvanrossum commented Sep 25, 2017

elazarg commented Sep 25, 2017

gvanrossum left a comment

emmatyping Sep 25, 2017

elazarg commented Sep 25, 2017

ilevkivskyi commented Sep 25, 2017

gvanrossum commented Sep 25, 2017 via email

emmatyping Sep 25, 2017

elazarg commented Sep 26, 2017

gvanrossum left a comment

gvanrossum Sep 25, 2017

gvanrossum Sep 25, 2017

elazarg Sep 26, 2017

ilevkivskyi Sep 26, 2017

ilevkivskyi Sep 26, 2017

elazarg Sep 26, 2017

ilevkivskyi Sep 26, 2017

elazarg Sep 26, 2017

gvanrossum left a comment

		@@ -168,8 +168,7 @@ In Windows, the script is generally installed in
		C:\>\Python34\python \Python34\Scripts\mypy PROGRAM

		If you are on Windows using Python 3.3 or 3.4, and would like to use XML reports

README.md: rearrange first paragraph to be more friendly #4002

README.md: rearrange first paragraph to be more friendly #4002

Conversation

elazarg commented Sep 25, 2017

Choose a reason for hiding this comment

gvanrossum commented Sep 25, 2017

elazarg commented Sep 25, 2017

gvanrossum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elazarg commented Sep 25, 2017

ilevkivskyi commented Sep 25, 2017

gvanrossum commented Sep 25, 2017 via email

Choose a reason for hiding this comment

elazarg commented Sep 26, 2017

gvanrossum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum left a comment

Choose a reason for hiding this comment