Specify that assert_type() uses equivalence

conformance/results/mypy/directives_assert_type.toml

@@ -1,13 +1,14 @@
 conformant = "Pass"
 output = """
 directives_assert_type.py:27: error: Expression is of type "int | str", not "int"  [assert-type]
-directives_assert_type.py:28: error: Expression is of type "Any", not "int"  [assert-type]
-directives_assert_type.py:29: error: Expression is of type "Literal[4]", not "int"  [assert-type]
-directives_assert_type.py:31: error: "assert_type" expects 2 arguments  [misc]
-directives_assert_type.py:31: error: Too few arguments for "assert_type"  [call-arg]
-directives_assert_type.py:32: error: Expression is of type "Literal['']", not "int"  [assert-type]
-directives_assert_type.py:33: error: "assert_type" expects 2 arguments  [misc]
-directives_assert_type.py:33: error: Too many arguments for "assert_type"  [call-arg]
+directives_assert_type.py:28: error: Expression is of type "int | str", not "Any"  [assert-type]
+directives_assert_type.py:29: error: Expression is of type "Any", not "int"  [assert-type]
+directives_assert_type.py:30: error: Expression is of type "Literal[4]", not "int"  [assert-type]
+directives_assert_type.py:32: error: "assert_type" expects 2 arguments  [misc]
+directives_assert_type.py:32: error: Too few arguments for "assert_type"  [call-arg]
+directives_assert_type.py:33: error: Expression is of type "Literal['']", not "int"  [assert-type]
+directives_assert_type.py:34: error: "assert_type" expects 2 arguments  [misc]
+directives_assert_type.py:34: error: Too many arguments for "assert_type"  [call-arg]
 """
 conformance_automated = "Pass"
 errors_diff = """

conformance/results/mypy/version.toml

@@ -1,2 +1,2 @@
 version = "mypy 1.16.1"
-test_duration = 2.2
+test_duration = 2.1

conformance/results/pyre/directives_assert_type.toml

@@ -3,11 +3,13 @@ notes = """
 """
 output = """
 directives_assert_type.py:27:4 Assert type [70]: Expected `int` but got `Union[int, str]`.
-directives_assert_type.py:28:4 Assert type [70]: Expected `int` but got `typing.Any`.
-directives_assert_type.py:29:4 Assert type [70]: Expected `int` but got `typing_extensions.Literal[4]`.
-directives_assert_type.py:31:4 Missing argument [20]: Call `assert_type` expects argument in position 0.
-directives_assert_type.py:32:4 Assert type [70]: Expected `int` but got `typing_extensions.Literal['']`.
-directives_assert_type.py:33:4 Too many arguments [19]: Call `assert_type` expects 2 positional arguments, 3 were provided.
+directives_assert_type.py:28:4 Assert type [70]: Expected `typing.Any` but got `Union[int, str]`.
+directives_assert_type.py:29:4 Assert type [70]: Expected `int` but got `typing.Any`.
+directives_assert_type.py:30:4 Assert type [70]: Expected `int` but got `typing_extensions.Literal[4]`.
+directives_assert_type.py:32:4 Missing argument [20]: Call `assert_type` expects argument in position 0.
+directives_assert_type.py:33:4 Assert type [70]: Expected `int` but got `typing_extensions.Literal['']`.
+directives_assert_type.py:34:4 Too many arguments [19]: Call `assert_type` expects 2 positional arguments, 3 were provided.
+directives_assert_type.py:41:4 Assert type [70]: Expected `Union[typing_extensions.Literal['spam'], str]` but got `str`.
 """
 conformance_automated = "Pass"
 errors_diff = """

conformance/results/pyre/version.toml

@@ -1,2 +1,2 @@
 version = "pyre 0.9.23"
-test_duration = 10.7
+test_duration = 11.0

conformance/results/pyright/directives_assert_type.toml

@@ -1,11 +1,13 @@
 conformant = "Pass"
 output = """
 directives_assert_type.py:27:17 - error: "assert_type" mismatch: expected "int" but received "int | str" (reportAssertTypeFailure)
-directives_assert_type.py:28:17 - error: "assert_type" mismatch: expected "int" but received "Any" (reportAssertTypeFailure)
-directives_assert_type.py:29:17 - error: "assert_type" mismatch: expected "int" but received "Literal[4]" (reportAssertTypeFailure)
-directives_assert_type.py:31:5 - error: "assert_type" expects two positional arguments (reportCallIssue)
-directives_assert_type.py:32:17 - error: "assert_type" mismatch: expected "int" but received "Literal['']" (reportAssertTypeFailure)
-directives_assert_type.py:33:5 - error: "assert_type" expects two positional arguments (reportCallIssue)
+directives_assert_type.py:28:17 - error: "assert_type" mismatch: expected "Any" but received "int | str" (reportAssertTypeFailure)
+directives_assert_type.py:29:17 - error: "assert_type" mismatch: expected "int" but received "Any" (reportAssertTypeFailure)
+directives_assert_type.py:30:17 - error: "assert_type" mismatch: expected "int" but received "Literal[4]" (reportAssertTypeFailure)
+directives_assert_type.py:32:5 - error: "assert_type" expects two positional arguments (reportCallIssue)
+directives_assert_type.py:33:17 - error: "assert_type" mismatch: expected "int" but received "Literal['']" (reportAssertTypeFailure)
+directives_assert_type.py:34:5 - error: "assert_type" expects two positional arguments (reportCallIssue)
+directives_assert_type.py:41:17 - error: "assert_type" mismatch: expected "str | Literal['spam']" but received "str" (reportAssertTypeFailure)
 """
 conformance_automated = "Pass"
 errors_diff = """

conformance/results/pyright/version.toml

@@ -1,2 +1,2 @@
 version = "pyright 1.1.402"
-test_duration = 1.8
+test_duration = 2.0

conformance/results/results.html

@@ -159,13 +159,13 @@ <h3>Python Type System Conformance Test Results</h3>
         <div class="table_container"><table><tbody>
 <tr><th class="col1">&nbsp;</th>
 <th class='tc-header'><div class='tc-name'>mypy 1.16.1</div>
-<div class='tc-time'>2.2sec</div>
+<div class='tc-time'>2.1sec</div>
 </th>
 <th class='tc-header'><div class='tc-name'>pyright 1.1.402</div>
-<div class='tc-time'>1.8sec</div>
+<div class='tc-time'>2.0sec</div>
 </th>
 <th class='tc-header'><div class='tc-name'>pyre 0.9.23</div>
-<div class='tc-time'>10.7sec</div>
+<div class='tc-time'>11.0sec</div>
 </th>
 </tr>
 <tr><th class="column" colspan="4">
@@ -324,7 +324,7 @@ <h3>Python Type System Conformance Test Results</h3>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;generics_type_erasure</th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Infers Node[Never] instead of Node[Any] when argument is not provided.</p><p>False negative on instance attribute access on type(node).</p></span></div></th>
-<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Missing error regarding `type(instance).generic_attribute`.</p></span></div></th>
+<th class="column col2 conformant">Pass</th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not erase unspecified type variables to `Any` prior to `assert_type` handling.</p><p>False negatives on instance attribute access on the type.</p><p>Does not infer type of `DefaultDict` with explicit type parameters on constructor.</p><p>False negatives on assert_type uses.</p></span></div></th>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;generics_typevartuple_args</th>
@@ -423,7 +423,7 @@ <h3>Python Type System Conformance Test Results</h3>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;aliases_newtype</th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>`NewType`s are considered classes, not functions.</p></span></div></th>
-<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>`NewType`s are considered classes, not functions.</p></span></div></th>
+<th class="column col2 conformant">Pass</th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not reject use of NewType in `isinstance` call.</p><p>Does not reject use of NewType in class definition statement.</p><p>Does not report inconsistency between name of NewType and assigned identifier name.</p><p>Does not reject use of NewType with generic class with TypeVar.</p><p>Does not reject use of NewType with protocol class.</p><p>Does not reject use of NewType with TypedDict class.</p><p>Does not reject use of NewType with Any.</p></span></div></th>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;aliases_recursive</th>

conformance/tests/directives_assert_type.py

@@ -25,6 +25,7 @@ def func1(
     assert_type(e, Literal[4])  # OK
 
     assert_type(a, int)  # E: Type mismatch
+    assert_type(a, Any)  # E: Type mismatch
     assert_type(c, int)  # E: Type mismatch
     assert_type(e, int)  # E: Type mismatch
 
@@ -33,5 +34,12 @@ def func1(
     assert_type(a, int | str, a)  # E: too many arguments
 
 
+# > If the two types are :term:`equivalent` but syntactically different,
+# > the type checker may reject the ``assert_type()`` call::
+
+def func2(name: str):
+    assert_type(name, str | Literal["spam"])  # E?: Equivalent but not identical
+
+
 class ForwardReference:
     pass

docs/spec/directives.rst

@@ -9,7 +9,8 @@ Type checker directives
 -----------------
 
 The function ``typing.assert_type(val, typ)`` allows users to
-ask a static type checker to confirm that *val* has an inferred type of *typ*.
+ask a static type checker to confirm that the inferred type of *val*
+is :term:`equivalent` to *typ*.
 
 When a type checker encounters a call to ``assert_type()``, it
 should emit an error if the value is not of the specified type::
@@ -18,6 +19,17 @@ should emit an error if the value is not of the specified type::
         assert_type(name, str)  # OK, inferred type of `name` is `str`
         assert_type(name, int)  # type checker error
 
+If the two types are :term:`equivalent` but syntactically different,
+the type checker may reject the ``assert_type()`` call::
+
+  from typing import assert_type, Literal
+
+  def greet(name: str) -> None:
+      assert_type(name, str | Literal["spam"])  # type checker may error
+
+Type checkers should aim to minimize cases where they reject
+``assert_type()`` calls that use equivalent types.
+
 The second argument must be a valid :term:`type expression`.
 
 .. _`reveal-type`: