Update error examples in documentation #3404

vilmibm · 2017-05-22T22:18:31Z

This addresses #2393.

In addition to adding actual error strings, there are some minor grammar and format edits.

To increase google-ability, this commit adds actual error messages where appropriate. This commit also contains some very minor grammar and sentence editing.

the x: List[str] = [] style of declaration is new in 3.6 and used throughout this doc. For users who might be reading this doc and using an older python, this section explains the older # type: List[str] format.

gvanrossum

Just a few nits.

gvanrossum · 2017-05-22T22:39:41Z

docs/source/common_issues.rst


 You often need to specify the type when you assign an empty list or
-dict to a new variable, as mentioned earlier:
+dict to a new variable.


gvanrossum · 2017-05-22T22:39:55Z

docs/source/common_issues.rst

-   a = []  # type: List[int]
+   a = []  # error: Need type annotation for variable
+
+


No need for two blank lines.

gvanrossum · 2017-05-22T22:40:25Z

docs/source/common_issues.rst


-Without the annotation mypy can't always figure out the
-precise type of ``a``.



Fewer blank lines here too.

gvanrossum · 2017-05-22T22:41:37Z

docs/source/common_issues.rst


-   shape = Circle() # type: Shape   # The variable s can be any Shape,
-                                    # not just Circle
+   shape: Shape = Circle()  # The variable s can be any Shape,


I'm not sure I agree with changing this -- it uses syntax that only works in Python 3.6.

That was per @ilevkivskyi 's suggestion, which is why I added the new section at the end about falling back to the pre 3.6 syntax. Perhaps I can demonstrate both in the code example?

I prefer to use the same stance as the PY3 cheatsheet: use # type: comments in most places, call out the new PEP 526 syntax in one place.

Backwards compatibility is still important to most people!

I agree we don't need to change existing docs with respect to PEP 526 syntax.
(Although, I think it is OK to use it from time to time in new docs.)

Sounds good! Sorry if I misunderstood. I'll take out the section I added, use # type everywhere, and then mention PEP 526 once in the initial introduction of the variable typing.

gvanrossum

OK on the whitespace nits.

Will comment separately on the other thing.

This commit switches variable type annotations back to pre python 3.6 syntax and notes the new syntax when variable type annotations are introduced.

- Adds an actual error to code samples where appropriate - Fixes some grammatical issues - Fixes some whitespace - Removes some inconsistencies in formatting - Fixes some illegal Python samples (ie forgetting `pass`)

vilmibm · 2017-05-23T23:52:02Z

This is ready for feedback, now.

ilinum

Sorry for the long response!

Overall it looks good!
Had just a few comments.

ilinum · 2017-07-07T21:51:00Z

docs/source/cheat_sheet.rst

                  ):
       # type: (...) -> bool
-        <code>
+       pass


I think it might be better to keep <code> here because if you put pass it technically doesn't typecheck. Or, perhaps, we can make the return type of the function None instead of bool.

Whoops, just tested it and pass does typecheck :)
I think it's okay to leave pass there then.

ilinum · 2017-07-07T21:54:58Z

docs/source/cheat_sheet.rst

-   reveal_type(c)  # -> error: Revealed type is 'builtins.list[builtins.str]'
-   print(c)  # -> [4] the object is not cast
+   reveal_type(c)  # error: Revealed type is 'builtins.list[builtins.str]'
+   print(c)  # [4] the object is not cast


Perhaps, it would be good to give an indication that [4] is the output of the print statement.
Something like

print(c) # prints [4] because the cast did not change the object's type at runtime

ilinum · 2017-07-07T21:55:35Z

docs/source/cheat_sheet_py3.rst

-   reveal_type(c)  # -> error: Revealed type is 'builtins.list[builtins.str]'
-   print(c)  # -> [4] the object is not cast
+   reveal_type(c)  # error: Revealed type is 'builtins.list[builtins.str]'
+   print(c)  # [4] the object is not cast


See comment for py2 cheatsheet.

ilinum · 2017-07-07T22:01:15Z

docs/source/common_issues.rst

+
+.. code-block:: python
+
+   a = [] # type: List[int]


I think it would make more sense to flip the two examples.

Something like the following (I'm omitting the exact words there)

1 -- You often need to specify the type...: a = [] # type: List[int] Without the annotation... a = [] # error: Need type annotation for variable

ilinum · 2017-07-07T22:02:54Z

docs/source/common_issues.rst

   lst = [A(), A()]  # Inferred type is List[A]
   new_lst = [B(), B()]  # inferred type is List[B]
-   lst = new_lst  # mypy will complain about this, because List is invariant
+   lst = new_lst  # error: Incompatible types in assignment (expression


I think it's worth mentioning that mypy complains about the assignment because of the fact that List is invariant.

ilinum · 2017-07-07T22:07:06Z

docs/source/common_issues.rst

           o = cast(int, o)
-           g(o + 1)    # This would be an error without the cast
+           g(o + 1)  # This would be an error without the cast:
+                     # error: Unsupported operand types for + ("object" and "int")


I think it's confusing to write out the error since it doesn't actually happen. I would just leave this comment as is.

Alternatively, you can have the following:

g(o + 1) # error: Unsupported operand types for + ("object" and "int") o = cast(int, o) g(o + 1) # This would be an error without the cast

ilinum · 2017-07-07T22:08:19Z

docs/source/common_issues.rst

-   in Python, if you try to run your program. You'll have to remove
-   any ``reveal_type`` calls before you can run your code.
-   ``reveal_type`` is always available and you don't need to import it.
+   in Python. You'll have to remove any ``reveal_type`` calls before you run


nit: remove all reveal_type calls

ilinum · 2017-07-07T22:14:13Z

docs/source/kinds_of_types.rst

    tcp_packet = TcpPacketId(packet)  # OK

-    tcp_packet = TcpPacketId(127, 0)  # Fails in type checker and at runtime
+    tcp_packet = TcpPacketId(127, 0)  # error: Too many arguments for "TcpPacketId"


Perhaps, it would be good to point out that this line fails both in typechecker and at runtime.

ilinum · 2017-07-07T22:16:59Z

docs/source/kinds_of_types.rst

-Python 3.6 will have an alternative, class-based syntax for named tuples with types.
-Mypy supports it already:
+Python 3.6 has an alternative, class-based syntax for named tuples with types,
+which Mypy supports:


I don't think we need to say which Mypy supports -- that is implied.

It was not obvious before Python 3.6 was released but now it is.

JukkaL · 2017-11-24T16:22:17Z

@vilmibm Are you interested in finishing up this PR? There is one merge conflict now.

emmatyping · 2017-12-16T02:59:23Z

@vilmibm feel free to leave a message if you feel like working on this again. Closing for now.

gvanrossum · 2017-12-16T06:10:15Z

(This is an example of a PR where less would have been more -- if it had been broken up into a few smaller parts the majority would probably have landed long ago...)

vilmibm added 2 commits May 22, 2017 15:07

use actual error messages when giving examples

8e4296b

To increase google-ability, this commit adds actual error messages where appropriate. This commit also contains some very minor grammar and sentence editing.

add section on variable type declaration

9a32a15

the x: List[str] = [] style of declaration is new in 3.6 and used throughout this doc. For users who might be reading this doc and using an older python, this section explains the older # type: List[str] format.

gvanrossum requested changes May 22, 2017

View reviewed changes

minor whitespace/punctuation changes

94aa1ba

gvanrossum approved these changes May 23, 2017

View reviewed changes

Favor pre 3.6 variable type annotation

49ec476

This commit switches variable type annotations back to pre python 3.6 syntax and notes the new syntax when variable type annotations are introduced.

vilmibm changed the title ~~Update error examples in Common Issues documentation~~ [WIP] Update error examples in documentation May 23, 2017

finish auditing errors in docs

208ced4

- Adds an actual error to code samples where appropriate - Fixes some grammatical issues - Fixes some whitespace - Removes some inconsistencies in formatting - Fixes some illegal Python samples (ie forgetting `pass`)

vilmibm changed the title ~~[WIP] Update error examples in documentation~~ Update error examples in documentation May 23, 2017

ilinum self-assigned this Jul 7, 2017

ilinum reviewed Jul 7, 2017

View reviewed changes

emmatyping closed this Dec 16, 2017

jbiersdo mentioned this pull request Dec 4, 2025

Updates error examples in Common Issues page for Issue #2393 #20362

Open

		a = [] # type: List[int]
		a = [] # error: Need type annotation for variable


		Without the annotation mypy can't always figure out the
		precise type of ``a``.

Uh oh!

Update error examples in documentation #3404

Update error examples in documentation #3404

Uh oh!

Conversation

vilmibm commented May 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

vilmibm commented May 23, 2017

Uh oh!

ilinum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ilinum Jul 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JukkaL commented Nov 24, 2017

Uh oh!

emmatyping commented Dec 16, 2017

Uh oh!

gvanrossum commented Dec 16, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vilmibm commented May 22, 2017 •

edited

Loading

ilinum Jul 7, 2017 •

edited

Loading