Add informative notes to invariant function arguments #3411

quartox · 2017-05-22T23:18:24Z

Note that the check.test files must now use out since there is a # in the documentation url, which breaks the # E: syntax.

gnprice · 2017-05-22T23:31:20Z

Thanks for this fix!

Note that the check.test files must now use out since there is a # in the documentation url, which breaks the # E: syntax.

Hmm. Kind of a shame to move all of these to the out form -- both because it's a little harder to read in itself (as the reader now loses the convenience of having the message right there on the line it's about), and because it makes the diff bigger and therefore harder to understand. I suspect this issue wouldn't be hard to fix -- want to do that first?

gnprice · 2017-05-22T23:34:25Z

Alternatively -- these URLs are already pretty long. Maybe move this docs section to its own page? :-)

quartox · 2017-05-22T23:36:04Z

Moving to a new page would do it. The current section is very far down the page, so difficult to expect the user to find it easily.
An alternative would be allow some form of escaping the # character in the check*.test files.

gvanrossum · 2017-05-22T23:51:05Z

Agreed we shouldn't have # in the URL.

…

On May 22, 2017 4:36 PM, "Jesse Lord" ***@***.***> wrote: Moving to a new page would do it. The current section is very far down the page, so difficult to expect the user to find it easily. An alternative would be allow some form of escaping the # character in the check*.test files. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3411 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACwrMrjoJS-J90TVUDPGir7Itko6-RD3ks5r8hvmgaJpZM4Ni_1w> .

gnprice · 2017-05-23T00:04:18Z

Even better than making a new page (though we can also do that too): I think we should make a redirect on RTD from some nice, shorter path (like variance?) to wherever we have it documented (like common_issues.html#invariance-vs-covariance).

That'd shorten the URL, get the # out -- and also give us the flexibility to move and rename that bit of the docs over time and preserve the links in existing versions of mypy.

Would want to put a comment in the docs source saying that the redirect should be updated when moved or renamed. We'd want a comment like that with or without the redirect, if we're going to link to it from error messages.

gvanrossum · 2017-05-23T00:09:36Z

The RTD redirect sounds too fancy (and too RTD-specific). Let's just move the explanation of *variance to its own page, to be named variance.html. It's worth it.

gnprice · 2017-05-23T00:10:27Z

I just made such a redirect a few minutes ago as an experiment -- if I'm understanding the admin UI and the docs right, it ought to show up at http://mypy.readthedocs.io/en/latest/variance .

That URL 404s right now. Maybe it takes some time to propagate? Not super confidence-inspiring; there's no mention of that that I can see in the interface or the docs.

gnprice · 2017-05-23T00:12:41Z

I'm slightly concerned, but only slightly, about it being RTD-specific -- I assume that basically any reasonable way of hosting web pages now and in the future, especially one oriented to documentation, has some way of redirecting one page's URL to another. I do wish that the way to express the redirect were in the docs' source tree rather than in an RTD admin UI on the web.

quartox · 2017-05-23T00:22:44Z

Successfully splitting check*.test files on ' # ' (instead of '#') with all existing tests passing. This seems like an appropriate choice to me, but judge for yourself. Let me know if you settle on re-direct vs new html and we can fix the url.

gnprice · 2017-05-23T00:22:49Z

OK, it's been at least 10 minutes and that URL doesn't work, and also after some more discussion I'm convinced we don't want to rely on RTD's implementation of anything fancy for us.

Let's just move that section to a new page variance -- that'll be a very sensible page for us to have forever. Let's move that in this same PR.

The change to split on # is a nice cleanup in any case, I think; I'd be glad to see it as a separate tiny PR.

quartox · 2017-05-23T00:29:45Z

I just did a straight move from to a new file. I have no experience with sphinx so don't know how to test that it builds the docs correctly.

gnprice · 2017-05-23T17:42:23Z

(Update FTR for whatever it means about RTD: http://mypy.readthedocs.io/en/latest/variance is still a 404 page.)

gnprice · 2017-05-23T17:57:56Z

@quartox No experience needed! Take a look at docs/README.md for how to build and view changes you make in the docs.

quartox · 2017-05-23T21:24:56Z

@gnprice

ilevkivskyi · 2017-08-19T21:11:27Z

mypy/messages.py

+        elif (arg_type.type.fullname() == 'builtins.dict' and
+              expected_type.type.fullname() == 'builtins.dict' and
+              arg_type.args[0].type == expected_type.args[0].type and
+              arg_type.args[1].type != expected_type.args[1].type):


There is something important here missing (also for List): we should show the note only when using a covariant type will actually help, for example here:

x: List[int] y: List[str] x = y

we don't need to show any notes, since using Sequence will not help. So that instead arg_type.args[1].type != expected_type.args[1].type use if subtypes.is_subtype(arg_type.args[1], expected_type.args[1]).

ilevkivskyi · 2017-08-19T21:15:51Z

test-data/unit/check-varargs.test

+f(a) # E: Argument 1 to "f" has incompatible type List[int]; expected List[Union[int, float]] \
+# N: "List" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Sequence" instead, which is covariant
+[builtins fixtures/list.pyi]


Add tests:

for tricky names (like DictReader)

for unrelated list types (like List[str] vs List[int]), see my comment above

for situations where covariance will help, and where it will not (like Dict[str, float] vs Dict[str, int] and vice-versa).

In general, it is a good idea to add tests for all situations that appeared in the discussion of a PR.

ilevkivskyi · 2017-08-19T21:27:59Z

mypy/messages.py

+            invariant_type = 'Dict'
+            covariant_suggestion = ('Consider using "Mapping" instead, '
+                                    'which is covariant in the value')
+    if invariant_type:


This will crash, since invariant_type is not always defined.

ilevkivskyi · 2017-08-19T21:30:12Z

mypy/messages.py

+              arg_type.args[1].type != expected_type.args[1].type):
+            invariant_type = 'Dict'
+            covariant_suggestion = ('Consider using "Mapping" instead, '
+                                    'which is covariant in the value')


"... covariant in the value type", if don't agree with a previous comment #3411 (comment), then please explain, just ignoring it is not a good option, I will not forget :-)

I just missed it, thanks for catching.

I am also not convinced that this message is clear to a novice user (which I expect is the intended audience for this type of note), but I can't think of a better concise message. I guess this assumes that the link is the most helpful part.

...at least value type suggests this is something related to types, not with the value itself (note that this error might appear in situations where list/dict literals are involved).

ilevkivskyi · 2017-08-19T21:32:13Z

mypy/messages.py

@@ -992,6 +997,28 @@ def pretty_or(args: List[str]) -> str:
    return ", ".join(quoted[:-1]) + ", or " + quoted[-1]


+def invariance_notes(notes: List[str], arg_type: Type, expected_type: Type) -> List[str]:
+    """Explain that the type is invariant and give notes for how to solve the issue."""
+    if isinstance(arg_type, Instance) and isinstance(expected_type, Instance):


I proposed to place this at the call site of this function not at the definition site, to avoid unnecessary calls.
(Also this will save you 4 spaces of indent.)

ilevkivskyi · 2017-08-19T21:45:06Z

mypy/messages.py

+                                    'which is covariant in the value')
+    if invariant_type and covariant_suggestion:
+        notes.append(
+            '"{}" is invariant --- see '.format(invariant_type) +


also I proposed two dashes here instead of three.

ilevkivskyi · 2017-08-19T21:46:26Z

@quartox It looks like several comments are still not addressed, please ping me back when you are ready.

quartox · 2017-08-19T21:55:41Z

@ilevkivskyi I have updated to address comments, but I am using the CI to check tests for me since my machine is very underpowered. I plan to address failing tests and we should be ready for more review after the tests are passing.

quartox · 2017-08-19T22:18:47Z

@ilevkivskyi the function definition now runs over 100 characters, what is the preferred way to move part to the next line?

quartox · 2017-08-19T22:20:38Z

mypy/messages.py

@@ -992,6 +998,31 @@ def pretty_or(args: List[str]) -> str:
    return ", ".join(quoted[:-1]) + ", or " + quoted[-1]


+def append_invariance_notes(notes: List[str], arg_type: Instance, expected_type: Instance) -> List[str]:


@ilevkivskyi Sorry, this is an easier way to make this comment. What is the preferred way to move part of this definition to the next line?

Like this:

def append_invariance_notes(notes: List[str], arg_type: Instance, expected_type: Instance) -> List[str]:

ilevkivskyi · 2017-08-19T22:32:41Z

test-data/unit/check-varargs.test

@@ -592,3 +592,51 @@ class C:
    def foo(self) -> None: pass
 C().foo()
 C().foo(1)  # The decorator's return type says this should be okay
+
+


One empty line between tests is enough (also below).

ilevkivskyi · 2017-08-19T22:33:30Z

test-data/unit/check-varargs.test

+
+[case testInvariantTypeConfusingNames]
+from typing import TypeVar
+DictReader = TypeVar('DictReader')


Why do you need a type variable here, just make these normal (empty) classes.

Thanks, I was struggling to figure out how to do this correctly. Do I need an __init__ method? Or is class DictReader enough?

Just class DictReader: pass.

ilevkivskyi · 2017-08-19T22:38:31Z

test-data/unit/check-inference.test

@@ -684,7 +684,7 @@ g('a')() # E: List[str] not callable
 # to backtrack later) and defaults to T = <nothing>. The result is an
 # awkward error message. Either a better error message, or simply accepting the
 # call, would be preferable here.
-g(['a']) # E: Argument 1 to "g" has incompatible type List[str]; expected List[<nothing>]
+g(['a']) # E: Argument 1 to "g" has incompatible type List[str]; expected List[<nothing>] 


Remove the trailing space at the end of this line.

ilevkivskyi

OK, hopefully two last comments.

ilevkivskyi · 2017-08-19T22:46:24Z

mypy/messages.py

+          expected_type.type.fullname() == 'builtins.dict' and
+          isinstance(arg_type.args[0], Instance) and
+          isinstance(expected_type.args[0], Instance) and
+          arg_type.args[0].type == expected_type.args[0].type and


Instead of this construction of three lines you can just use sametypes.is_same_types (if I remember the name correctly). This will allow other types, (like Union etc.) as well, and it is simpler.

I mean sametypes.is_same_types(arg_type.args[0], expected_type.args[0])

ilevkivskyi · 2017-08-19T22:49:22Z

test-data/unit/check-varargs.test

+d = {'d': 1}
+f(a) # E: Argument 1 to "f" has incompatible type Dict[str, List[int]]; expected Dict[str, Sequence[int]] \
+# N: "Dict" is invariant -- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Mapping" instead, which is covariant in the value type


Could you please format this with indents like this:

f(a) # E: Argument 1 to "f" has incompatible type Dict[str, List[int]]; expected Dict[str, Sequence[int]] \ # N: "Dict" is invariant -- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \ # N: Consider using "Mapping" instead, which is covariant in the value type

here and elsewhere, it is much easier to read.

quartox · 2017-08-19T22:56:00Z

@ilevkivskyi Excellent, I just pushed the fixes. Thank you very much for your help. I know it was probably frustrating, but I learned a lot from the experience. Let me know if there are any more comments.

ilevkivskyi

Thanks! LGTM now, will merge when tests pass.

quartox added 4 commits May 22, 2017 13:30

Add notes to invariant argument error

4f6d386

Fix type inference

c12fc40

Add invariant notes to tests

2b92465

Remove stray comment

05a8ee8

gnprice self-assigned this May 22, 2017

Split tests on ' # ' instead of '#'

1bf5a93

Move variance to new page

5a70c57

quartox added 2 commits May 22, 2017 17:33

Update doc url in invariant notes

b0536d5

Revert to split on '#' for check tests

fa4093d

quartox added 4 commits May 23, 2017 11:12

Add variance to toc

2888c5f

Move docs to correct files

f8700c3

Switch order in toc

572160d

Revert docs

900a927

gnprice mentioned this pull request May 23, 2017

Move variance docs to new page #3429

Merged

quartox added 2 commits May 24, 2017 15:13

Improve test readability

2fee5be

Merge branch 'master' into invariance_notes

823e1c2