type-assert 0.1.0__tar.gz → 0.2.1__tar.gz

{type_assert-0.1.0 → type_assert-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: type-assert
-Version: 0.1.0
+Version: 0.2.1
 Summary: pytest plugin that checks a value static type and its runtime type in one assertion
 Author: user27182
 License-Expression: MIT
@@ -122,6 +122,62 @@ it catches a `None` at any position in a `list[int]`, not only the first element
 
 Writing the type once covers both halves, and there is no way for them to drift apart.
 
+## What each half checks
+
+The checker's `assert_type` is exact: the inferred type must be the expected type, so
+`object` fails for an `int` and `list[float]` fails for a `list[int]`. The runtime
+check is assignability, the relation the type system itself uses for a value: an
+instance of a subclass passes for its base class, and every element of a container is
+held to the same rule.
+
+Two things are read more strictly than the type system would, because they are where a
+declared type and a produced value drift apart in practice:
+
+- A number has to be an instance of the numeric class named. An `int` does not pass for
+  `float`, a `bool` does not pass for `int`, and `[1, 2]` does not pass for
+  `list[float]`. A function that really returns either should say `float | int`.
+- A NumPy array is checked as the array type it actually is, dtype and number of
+  dimensions included, so a `float64` array does not pass for `NDArray[np.int64]`
+  and a 1-D array does not pass for `ndarray[tuple[int, int], ...]`.
+
+Both apply at any depth inside lists, tuples, sets and dicts. What the runtime half
+cannot check is a type argument the value does not carry: a `Box[int]` is only a `Box`
+at runtime, and there the checker is the sole authority. A supertype still fails only
+the static half, which is the intended division of labour: the checker guards what was
+declared, the run guards what was produced, and a case passes only when the declaration
+is exact and the value honours it.
+
+## Types that only a checker can spell
+
+Some types have no runtime spelling: a name imported under `TYPE_CHECKING`, or a class
+a checker treats as generic that cannot be subscripted at runtime, such as
+`np.dtype[np.generic[object]]`. Write the type as a string, the way an annotation can be
+quoted:
+
+```python
+assert_types(dtype_of(array), 'np.dtype[np.generic[object]]')
+```
+
+The checker reads the string as the type it names and holds the case to it exactly. At
+runtime the string is evaluated in the case file's namespace. When that succeeds the
+value is checked against it as usual, so a wrong quoted type still fails both halves.
+When the type cannot be built, the runtime half is skipped with the reason, since there
+is nothing to check the value against.
+
+To keep a runtime check as well, name the type under `TYPE_CHECKING` and give it a
+runtime stand-in:
+
+```python
+if TYPE_CHECKING:
+    DType = np.dtype[np.generic[object]]
+else:
+    DType = np.dtype
+
+assert_types(dtype_of(array), DType)
+```
+
+The checker still sees the exact type; the value is checked against the stand-in.
+
 ## Choosing a checker
 
 ```toml
@@ -163,6 +219,18 @@ after the file's setup has run, so making an entry conditional is ordinary Pytho
 entry naming an expression that no case makes fails the file's `setup` test, so a skip
 cannot quietly outlive the case it was written for.
 
+## Running the cases on their own
+
+Case files collect like any other test file, so a job can run just them:
+
+```bash
+pytest tests/typing/cases --no-cov
+```
+
+pytest-cov's `--no-cov` matters when the project sets a coverage threshold in
+`addopts`: the cases exercise only what they call, so `--cov-fail-under` would fail a
+run that is only about types. Runs of the whole suite are unaffected.
+
 ## License
 
 MIT

{type_assert-0.1.0 → type_assert-0.2.1}/README.md

@@ -82,6 +82,62 @@ it catches a `None` at any position in a `list[int]`, not only the first element
 
 Writing the type once covers both halves, and there is no way for them to drift apart.
 
+## What each half checks
+
+The checker's `assert_type` is exact: the inferred type must be the expected type, so
+`object` fails for an `int` and `list[float]` fails for a `list[int]`. The runtime
+check is assignability, the relation the type system itself uses for a value: an
+instance of a subclass passes for its base class, and every element of a container is
+held to the same rule.
+
+Two things are read more strictly than the type system would, because they are where a
+declared type and a produced value drift apart in practice:
+
+- A number has to be an instance of the numeric class named. An `int` does not pass for
+  `float`, a `bool` does not pass for `int`, and `[1, 2]` does not pass for
+  `list[float]`. A function that really returns either should say `float | int`.
+- A NumPy array is checked as the array type it actually is, dtype and number of
+  dimensions included, so a `float64` array does not pass for `NDArray[np.int64]`
+  and a 1-D array does not pass for `ndarray[tuple[int, int], ...]`.
+
+Both apply at any depth inside lists, tuples, sets and dicts. What the runtime half
+cannot check is a type argument the value does not carry: a `Box[int]` is only a `Box`
+at runtime, and there the checker is the sole authority. A supertype still fails only
+the static half, which is the intended division of labour: the checker guards what was
+declared, the run guards what was produced, and a case passes only when the declaration
+is exact and the value honours it.
+
+## Types that only a checker can spell
+
+Some types have no runtime spelling: a name imported under `TYPE_CHECKING`, or a class
+a checker treats as generic that cannot be subscripted at runtime, such as
+`np.dtype[np.generic[object]]`. Write the type as a string, the way an annotation can be
+quoted:
+
+```python
+assert_types(dtype_of(array), 'np.dtype[np.generic[object]]')
+```
+
+The checker reads the string as the type it names and holds the case to it exactly. At
+runtime the string is evaluated in the case file's namespace. When that succeeds the
+value is checked against it as usual, so a wrong quoted type still fails both halves.
+When the type cannot be built, the runtime half is skipped with the reason, since there
+is nothing to check the value against.
+
+To keep a runtime check as well, name the type under `TYPE_CHECKING` and give it a
+runtime stand-in:
+
+```python
+if TYPE_CHECKING:
+    DType = np.dtype[np.generic[object]]
+else:
+    DType = np.dtype
+
+assert_types(dtype_of(array), DType)
+```
+
+The checker still sees the exact type; the value is checked against the stand-in.
+
 ## Choosing a checker
 
 ```toml
@@ -123,6 +179,18 @@ after the file's setup has run, so making an entry conditional is ordinary Pytho
 entry naming an expression that no case makes fails the file's `setup` test, so a skip
 cannot quietly outlive the case it was written for.
 
+## Running the cases on their own
+
+Case files collect like any other test file, so a job can run just them:
+
+```bash
+pytest tests/typing/cases --no-cov
+```
+
+pytest-cov's `--no-cov` matters when the project sets a coverage threshold in
+`addopts`: the cases exercise only what they call, so `--cov-fail-under` would fail a
+run that is only about types. Runs of the whole suite are unaffected.
+
 ## License
 
 MIT

{type_assert-0.1.0 → type_assert-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ['setuptools>=64', 'setuptools_scm>=8']
 
 [dependency-groups]
 dev = ['pre-commit', 'pytest-cov', { include-group = 'test' }]
-test = ['mypy', 'pyrefly', 'pyright', 'pytest']
+test = ['mypy', 'numpy', 'pyrefly', 'pyright', 'pytest']
 
 [project]
 authors = [{ name = 'user27182' }]

{type_assert-0.1.0 → type_assert-0.2.1}/tests/test_assertions.py

@@ -18,6 +18,8 @@ from typing import Protocol
 from typing import Union
 from typing import runtime_checkable
 
+import numpy as np
+import numpy.typing as npt
 import pytest
 
 from type_assert import assert_types
@@ -103,17 +105,139 @@ REJECTED = [
 ]
 
 
+# Assignable to the type system, and rejected here all the same.
+PROMOTED = [
+    pytest.param(1, float, id='int-is-not-float'),
+    pytest.param(True, float, id='bool-is-not-float'),
+    pytest.param(True, int, id='bool-is-not-int'),
+    pytest.param(1, complex, id='int-is-not-complex'),
+    pytest.param(1.5, complex, id='float-is-not-complex'),
+    pytest.param([1, 2], list[float], id='list-of-int-is-not-list-of-float'),
+    pytest.param([1.5, 1], list[float], id='promoted-element-last'),
+    pytest.param((1.5, 1), tuple[float, float], id='fixed-tuple-member'),
+    pytest.param((1.5, 1), tuple[float, ...], id='variadic-tuple-member'),
+    pytest.param({1.5, 1}, set[float], id='set-member'),
+    pytest.param({'a': 1}, dict[str, float], id='dict-value'),
+    pytest.param({1: 'a'}, dict[float, str], id='dict-key'),
+    pytest.param([[1.5], [1]], list[list[float]], id='nested'),
+    pytest.param([1], Sequence[float], id='abc-sequence'),
+    pytest.param(1, Optional[float], id='optional'),
+    pytest.param(1, float | None, id='optional-pep604'),
+    pytest.param(1, float | str, id='no-union-member-fits-exactly'),
+    pytest.param([1.5, 1], list[float | str], id='union-element'),
+]
+
+# The stricter reading still lets through what it should.
+STILL_ACCEPTED = [
+    pytest.param(1.5, float, id='float-is-float'),
+    pytest.param(1, int, id='int-is-int'),
+    pytest.param(True, bool, id='bool-is-bool'),
+    pytest.param(1j, complex, id='complex-is-complex'),
+    pytest.param(1, float | int, id='union-names-the-class'),
+    pytest.param(1, int | float, id='union-in-either-order'),
+    pytest.param(None, float | None, id='none-for-optional-float'),
+    pytest.param([1.5, 2.5], list[float], id='list-of-float'),
+    pytest.param((1.5, 1), tuple[float, int], id='fixed-tuple-as-declared'),
+    pytest.param({'a': 1.5}, dict[str, float], id='dict-as-declared'),
+    pytest.param([[1.5]], list[list[float]], id='nested-as-declared'),
+    pytest.param(np.float64(1.5), float, id='numpy-float64-is-a-float'),
+    pytest.param(1, Any, id='any'),
+    pytest.param(1, object, id='object'),
+    pytest.param('a', Literal['a', 'b'], id='literal'),
+]
+
+
 @pytest.mark.parametrize(('value', 'expected'), ACCEPTED)
 def test_accepts(value, expected):
     assert_types(value, expected)
 
 
+@pytest.mark.parametrize(('value', 'expected'), PROMOTED)
+def test_rejects_what_the_type_system_would_merely_promote(value, expected):
+    with pytest.raises(AssertionError, match='does not have the expected type'):
+        assert_types(value, expected)
+
+
+@pytest.mark.parametrize(('value', 'expected'), STILL_ACCEPTED)
+def test_the_stricter_reading_accepts_what_is_declared(value, expected):
+    assert_types(value, expected)
+
+
+def test_the_stricter_failure_names_where_the_problem_is():
+    with pytest.raises(AssertionError) as error:
+        assert_types({'a': [1.5, 1]}, dict[str, list[float]])
+    assert "value['a'][1] is int 1, not float" in str(error.value)
+
+
+class TestArrays:
+    """A NumPy array is checked as the array type it is, dtype and dimensions included."""
+
+    def test_the_dtype_is_checked(self):
+        assert_types(np.array([1.0]), npt.NDArray[np.float64])
+        with pytest.raises(AssertionError, match='dtype float64'):
+            assert_types(np.array([1.0]), npt.NDArray[np.int64])
+
+    def test_a_union_of_dtypes_accepts_each_member(self):
+        assert_types(np.array([1], dtype=np.float32), npt.NDArray[np.float32 | np.float64])
+        with pytest.raises(AssertionError, match='does not have the expected type'):
+            assert_types(np.array([1]), npt.NDArray[np.float32 | np.float64])
+
+    def test_a_union_of_array_types_accepts_each_member(self):
+        assert_types(np.array([1]), npt.NDArray[np.float64] | npt.NDArray[np.int64])
+
+    def test_the_number_of_dimensions_is_checked(self):
+        matrix = np.ndarray[tuple[int, int], np.dtype[np.float64]]
+        assert_types(np.zeros((2, 2)), matrix)
+        with pytest.raises(AssertionError, match='1 dimension'):
+            assert_types(np.zeros(2), matrix)
+
+    def test_a_scalar_array_has_no_dimensions(self):
+        assert_types(np.array(1.0), np.ndarray[tuple[()], np.dtype[np.float64]])
+        assert_types(np.array(1.0), npt.NDArray[np.float64])
+
+    def test_an_unparametrised_array_type_accepts_any_array(self):
+        assert_types(np.array([1.0]), np.ndarray)
+
+    def test_arrays_inside_containers_are_checked(self):
+        assert_types([np.array([1])], list[npt.NDArray[np.int64]])
+        with pytest.raises(AssertionError, match=r'value\[0\] is an array of dtype float64'):
+            assert_types([np.array([1.0])], list[npt.NDArray[np.int64]])
+
+    def test_a_numpy_scalar_is_not_a_python_int(self):
+        # Not a promotion: np.int64 does not subclass int, so pycroscope rejects it.
+        with pytest.raises(AssertionError, match='not assignable'):
+            assert_types(np.int64(1), int)
+
+
 @pytest.mark.parametrize(('value', 'expected'), REJECTED)
 def test_rejects(value, expected):
     with pytest.raises(AssertionError, match='not assignable'):
         assert_types(value, expected)
 
 
+class TestQuotedTypes:
+    """A type written as a string is built where the assertion is made."""
+
+    def test_a_quoted_type_is_checked_rather_than_taken_for_any(self):
+        assert_types(1, 'int')
+        with pytest.raises(AssertionError, match='not assignable'):
+            assert_types('x', 'int')
+
+    def test_a_quoted_container_type_is_walked(self):
+        with pytest.raises(AssertionError, match='not assignable'):
+            assert_types([1, 'a'], 'list[int]')
+
+    def test_names_local_to_the_caller_are_visible(self):
+        class Local:
+            """Exists only inside this test."""
+
+        assert_types(Local(), 'Local')
+
+    def test_a_type_that_cannot_be_built_is_an_error_not_a_pass(self):
+        with pytest.raises(TypeError, match=r'cannot be built at runtime \(NameError'):
+            assert_types(1, 'NoSuchName')
+
+
 def test_returns_the_value_unchanged():
     value = [1, 2]
     assert assert_types(value, list[int]) is value

{type_assert-0.1.0 → type_assert-0.2.1}/tests/test_cases.py

@@ -163,6 +163,52 @@ class TestMalformed:
         assert case_file.cases == ()
 
 
+class TestQuotedTypes:
+    """A quoted expected type reads like an unquoted one, and may exist only for a checker."""
+
+    NEVER = (
+        'from typing import TYPE_CHECKING\n\n'
+        'if TYPE_CHECKING:\n'
+        '    from typing_extensions import Never\n\n\n'
+        'def empty() -> list[Never]:\n'
+        '    return []\n\n\n'
+        "assert_types(empty(), 'list[Never]')\n"
+    )
+
+    def test_the_id_drops_the_quotes(self, write):
+        case_file = write("assert_types(len([1]), 'int')\n")
+        assert case_file.cases[0].id == 'len([1]) -> int'
+        assert case_file.cases[0].quoted
+
+    def test_an_unquoted_type_is_not_marked_quoted(self, write):
+        case_file = write('assert_types(len([1]), int)\n')
+        assert not case_file.cases[0].quoted
+
+    def test_the_spelling_inside_the_quotes_is_normalised(self, write):
+        case_file = write("assert_types(len([1]), 'list[ int ]')\n")
+        assert case_file.cases[0].expected == 'list[int]'
+
+    def test_a_type_that_exists_at_runtime_is_checked(self, write):
+        case_file = write("assert_types(len([1]), 'str')\n")
+        with pytest.raises(AssertionError, match='not assignable'):
+            case_file.run(case_file.cases[0])
+
+    def test_a_type_that_cannot_be_built_skips_the_runtime_half(self, write):
+        case_file = write(self.NEVER)
+        with pytest.raises(CaseSkipped, match=r"'list\[Never\]' cannot be built at runtime"):
+            case_file.run(case_file.cases[0])
+
+    def test_the_skip_names_the_error(self, write):
+        case_file = write(self.NEVER)
+        with pytest.raises(CaseSkipped, match='NameError'):
+            case_file.run(case_file.cases[0])
+
+    def test_a_quoted_type_that_is_not_an_expression_is_malformed(self, write):
+        case_file = write("assert_types(len([1]), 'not a type')\n")
+        assert case_file.error is not None
+        assert 'not a type expression' in case_file.error
+
+
 class TestSkipping:
     """`SKIP_RUNTIME` takes the runtime half out, and only that."""
 

{type_assert-0.1.0 → type_assert-0.2.1}/tests/test_plugin.py

@@ -88,6 +88,20 @@ def test_a_wrong_runtime_value_fails_the_runtime_half(project):
     result.assert_outcomes(passed=3)
 
 
+def test_a_value_the_type_system_would_promote_fails_the_runtime_half(project):
+    # Returning an int for a declared float satisfies every checker, so only the
+    # runtime half can say that the declaration does not match what is produced.
+    source = (
+        'from type_assert import assert_types\n\n'
+        'def rounded() -> float:\n'
+        '    return 1\n\n'
+        'assert_types(rounded(), float)\n'
+    )
+    result = project(source).runpytest()
+    result.assert_outcomes(passed=2, failed=1)
+    result.stdout.fnmatch_lines(['*runtime*', '*is int 1, not float*'])
+
+
 def test_an_error_outside_a_case_fails_the_setup_test(project):
     source = (
         'from type_assert import assert_types\n\nBAD: int = "no"\nassert_types(len([1]), int)\n'
@@ -132,6 +146,49 @@ def test_a_skipped_case_skips_only_its_runtime_half(project):
     result.stdout.fnmatch_lines(['*a reason*'])
 
 
+QUOTED_NEVER = (
+    'from typing import TYPE_CHECKING\n\n'
+    'from type_assert import assert_types\n\n'
+    'if TYPE_CHECKING:\n'
+    '    from typing_extensions import Never\n\n\n'
+    'def empty() -> list[Never]:\n'
+    '    return []\n\n\n'
+    "assert_types(empty(), 'list[Never]')\n"
+)
+
+
+@pytest.mark.parametrize('checker', ['mypy', 'pyright'])
+def test_a_quoted_type_only_a_checker_can_build_is_checked_statically(project, checker):
+    result = project(QUOTED_NEVER, checkers=checker).runpytest('-rs')
+    result.assert_outcomes(passed=2, skipped=1)
+    result.stdout.fnmatch_lines(['*cannot be built at runtime*'])
+
+
+def test_a_case_file_named_on_the_command_line_is_collected_once_as_cases(project):
+    # pytest collects an explicitly named `.py` file as a test module whatever its
+    # name; importing this one would run the quoted assertion at import and fail.
+    result = project(QUOTED_NEVER).runpytest('cases/sample.py', '-rs')
+    result.assert_outcomes(passed=2, skipped=1, errors=0)
+    result.stdout.fnmatch_lines(['*cannot be built at runtime*'])
+
+
+def test_a_case_file_named_on_the_command_line_yields_the_same_tests(project):
+    result = project(CLEAN).runpytest('cases/sample.py', '--collect-only', '-q')
+    result.stdout.fnmatch_lines(['*::setup', '*len([[]1[]]) -> int [[]runtime[]]'])
+    assert result.stdout.str().count('[runtime]') == 2
+
+
+def test_a_quoted_type_the_runtime_can_build_is_held_to_by_both_halves(project):
+    source = (
+        'from type_assert import assert_types\n\n'
+        "assert_types(len([1]), 'int')\n"
+        "assert_types(len([1]), 'str')\n"
+    )
+    result = project(source).runpytest()
+    # The right type passes both halves and the wrong one fails both: quoting weakens neither.
+    result.assert_outcomes(passed=3, failed=2)
+
+
 def test_a_skip_naming_no_case_fails_the_setup_test(project):
     source = (
         'from type_assert import assert_types\n\n'

type_assert-0.2.1/type_assert/_assertions.py

@@ -0,0 +1,94 @@
+"""The one assertion a typing case makes.
+
+To a type checker `assert_types` is `typing_extensions.assert_type`; at runtime it
+is a real checker. See the module body for why that works.
+
+The runtime check is assignability, read strictly in two places where a declared
+type and a produced value drift apart in practice: a number has to be an instance
+of the numeric class named, so an `int` does not pass for `float`, and a NumPy
+array is checked as the array type it actually is, dtype and dimensions included.
+
+The expected type may be quoted, as annotations may. A checker reads the string as
+the type it names; at runtime the string is evaluated in the caller's namespace, so
+it means the same thing to both halves.
+"""
+
+from __future__ import annotations
+
+import functools
+import sys
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+    # A checker resolves an aliased import back to its original definition, so it
+    # applies its `assert_type` special case here: the inferred type must match
+    # `expected` *exactly*, not merely be assignable to it. Verified against both
+    # mypy and pyright. At runtime the definition below runs instead and checks the
+    # value, so one call covers both halves and they cannot drift apart.
+    from typing_extensions import assert_type as assert_types
+else:
+    from pycroscope.checker import Checker
+    from pycroscope.runtime import CanAssignError
+    from pycroscope.runtime import KnownValue
+    from pycroscope.runtime import Relation
+    from pycroscope.runtime import has_relation
+    from pycroscope.runtime import type_from_runtime
+
+    from ._exact import mismatch
+
+    @functools.cache
+    def _checker() -> Checker:
+        """Return the shared checker, built on first use."""
+        return Checker()
+
+    def assert_types(value: object, expected: Any) -> object:
+        """Assert `value` is assignable to `expected` at runtime, and return it."""
+        if isinstance(expected, str):
+            expected = _resolve(expected, sys._getframe(1))
+        # pycroscope's own `get_assignability_error` memoises against a module-global
+        # checker, which keeps every checked value alive for the rest of the session.
+        # Use our own so the memo can be dropped after each check.
+        checker = _checker()
+        try:
+            relation = has_relation(
+                type_from_runtime(expected), KnownValue(value), Relation.ASSIGNABLE, checker
+            )
+            if isinstance(relation, CanAssignError):
+                msg = (
+                    f'Runtime value of type {type(value).__name__!r} is not assignable '
+                    f'to the expected type:\n\t{expected}\n\n{relation.display(depth=0)}'
+                )
+                # An assertion that failed, not a caller passing the wrong kind of argument.
+                raise AssertionError(msg)  # noqa: TRY004
+            problem = mismatch(value, expected, checker=checker)
+        finally:
+            cache = checker.get_relation_cache()
+            if cache is not None:
+                cache.clear()
+
+        if problem is not None:
+            msg = (
+                f'Runtime value of type {type(value).__name__!r} does not have the '
+                f'expected type:\n\t{expected}\n\n{problem}'
+            )
+            raise AssertionError(msg)
+        return value
+
+    def _resolve(expected: str, frame: FrameType) -> object:
+        """Build a quoted type in the caller's namespace, where a checker also reads it.
+
+        Left as a string, pycroscope would take it for an unresolvable forward
+        reference and check against `Any`, which passes for every value.
+        """
+        try:
+            return eval(expected, frame.f_globals, frame.f_locals)
+        except Exception as error:
+            msg = (
+                f'The expected type {expected!r} cannot be built at runtime '
+                f'({type(error).__name__}: {error}). A case file skips the runtime half '
+                f'of such a case; elsewhere, spell a type that exists at runtime.'
+            )
+            raise TypeError(msg) from error

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert/_cases.py

@@ -32,6 +32,9 @@ class Case:
     expression: str
     expected: str
     code: CodeType
+    #: Whether the expected type was written as a string. A checker reads it the same
+    #: way; at runtime it is built in the file's namespace, which may not be possible.
+    quoted: bool = False
 
     @property
     def id(self) -> str:
@@ -68,7 +71,7 @@ class CaseFile:
         cannot observe another's state, and reordering the file changes nothing.
         """
         namespace = self.setup_namespace()
-        reason = skip_reason(namespace, case)
+        reason = skip_reason(namespace, case) or unbuildable_reason(namespace, case)
         if reason is not None:
             raise CaseSkipped(reason)
         exec(case.code, namespace)  # noqa: S102
@@ -92,6 +95,26 @@ def skip_reason(namespace: dict[str, Any], case: Case) -> str | None:
     return declared.get(case.expression) or None
 
 
+def unbuildable_reason(namespace: dict[str, Any], case: Case) -> str | None:
+    """Return why `case`'s quoted type cannot be built at runtime, if it cannot.
+
+    A type that exists only for a checker -- a name imported under `TYPE_CHECKING`,
+    a class that cannot be subscripted at runtime -- can still be written as a
+    string. The checker holds the case to it; the runtime half has nothing to check
+    against, so it is skipped rather than failed.
+    """
+    if not case.quoted:
+        return None
+    try:
+        eval(case.expected, namespace)
+    except Exception as error:  # noqa: BLE001
+        return (
+            f'the expected type {case.expected!r} cannot be built at runtime '
+            f'({type(error).__name__}: {error}), so only a checker can check this case'
+        )
+    return None
+
+
 def _case_call(node: ast.AST) -> ast.Call | None:
     """Return the `assert_types` call a top-level statement makes, if it makes one."""
     if not isinstance(node, ast.Expr):
@@ -157,14 +180,16 @@ def _parse_case_file(path: Path) -> CaseFile:
         if len(call.args) != 2:
             msg = f'{path.name}:{node.lineno}: `{ASSERTION}` takes an expression and a type.'
             raise CaseError(msg)
+        expected, quoted = _expected_type(call.args[1], path, node.lineno)
         module = ast.Module(body=[node], type_ignores=[])
         cases.append(
             Case(
                 path=path,
                 lines=frozenset(range(node.lineno, (node.end_lineno or node.lineno) + 1)),
                 expression=ast.unparse(call.args[0]),
-                expected=ast.unparse(call.args[1]),
+                expected=expected,
                 code=compile(ast.fix_missing_locations(module), str(path), 'exec'),
+                quoted=quoted,
             )
         )
 
@@ -177,6 +202,22 @@ def _parse_case_file(path: Path) -> CaseFile:
     )
 
 
+def _expected_type(node: ast.expr, path: Path, lineno: int) -> tuple[str, bool]:
+    """Return the expected type as written, unquoted if it was a string, and whether it was.
+
+    Both spellings normalise to the same text, so a case reads the same in a test id
+    whichever way it was written.
+    """
+    if not (isinstance(node, ast.Constant) and isinstance(node.value, str)):
+        return ast.unparse(node), False
+    try:
+        tree = ast.parse(node.value, mode='eval')
+    except SyntaxError:
+        msg = f'{path.name}:{lineno}: the quoted type {node.value!r} is not a type expression.'
+        raise CaseError(msg) from None
+    return ast.unparse(tree.body), True
+
+
 def collect_cases(directory: Path) -> list[CaseFile]:
     """Parse every case file in `directory`."""
     return [collect_case_file(path) for path in sorted(directory.glob('*.py'))]

type_assert-0.2.1/type_assert/_exact.py

@@ -0,0 +1,165 @@
+"""The two ways the runtime half is stricter than plain assignability.
+
+pycroscope decides whether a value is assignable to a type the way the type system
+does, which lets an `int` pass for `float` and cannot see the type arguments of a
+NumPy array. Both are places where a declared type and a produced value drift apart
+in practice, so after pycroscope has accepted a value, `mismatch` walks it once more
+against the expected type and rejects those two things: a number that is not an
+instance of the numeric class named, and an array whose dtype or dimensionality is
+not the one named. Anything it does not understand it leaves to pycroscope's verdict.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from collections.abc import MutableMapping
+from collections.abc import MutableSequence
+from collections.abc import MutableSet
+from collections.abc import Sequence
+from collections.abc import Set as AbstractSet
+import sys
+from types import UnionType
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Union
+from typing import get_args
+from typing import get_origin
+
+from pycroscope.runtime import CanAssignError
+from pycroscope.runtime import KnownValue
+from pycroscope.runtime import Relation
+from pycroscope.runtime import has_relation
+from pycroscope.runtime import type_from_runtime
+
+if TYPE_CHECKING:
+    from pycroscope.checker import Checker
+
+# Numeric classes a value has to be an instance of, rather than merely promotable to.
+_NUMERIC = (float, int, complex)
+_SEQUENCES = (list, set, frozenset, Sequence, MutableSequence, AbstractSet, MutableSet)
+_MAPPINGS = (dict, Mapping, MutableMapping)
+
+
+def mismatch(value: object, expected: Any, *, checker: Checker, path: str = 'value') -> str | None:
+    """Return why `value` is not of `expected` under the stricter reading, or `None`.
+
+    Only called for a value pycroscope has already found assignable, so this never
+    has to accept anything; it only adds rejections, each naming where in the value
+    it found the problem.
+    """
+    if expected is Any or expected is object:
+        return None
+    origin = get_origin(expected)
+    if origin is Union or origin is UnionType:
+        return _mismatch_union(value, expected, checker=checker, path=path)
+    if expected in _NUMERIC:
+        return _mismatch_number(value, expected, path=path)
+    if origin in _SEQUENCES and isinstance(value, (list, tuple, set, frozenset)):
+        (item_type,) = get_args(expected) or (Any,)
+        return _mismatch_items(value, [item_type] * len(value), checker=checker, path=path)
+    if origin is tuple and isinstance(value, tuple):
+        return _mismatch_tuple(value, expected, checker=checker, path=path)
+    if origin in _MAPPINGS and isinstance(value, dict):
+        return _mismatch_mapping(value, expected, checker=checker, path=path)
+    ndarray = _ndarray_class()
+    if ndarray is not None and isinstance(value, ndarray) and _is_array_type(expected, ndarray):
+        return _mismatch_array(value, expected, checker=checker, path=path)
+    return None
+
+
+def _mismatch_union(value: object, expected: Any, *, checker: Checker, path: str) -> str | None:
+    """Accept a union if some member accepts the value under both readings."""
+    for member in get_args(expected):
+        if _assignable(member, KnownValue(value), checker) and (
+            mismatch(value, member, checker=checker, path=path) is None
+        ):
+            return None
+    return f'{path} is {_describe(value)}, which is not of any of {expected}'
+
+
+def _mismatch_number(value: object, expected: type, *, path: str) -> str | None:
+    """Require an instance of the numeric class named, not one promotable to it."""
+    if isinstance(value, expected) and not (expected is int and isinstance(value, bool)):
+        return None
+    return f'{path} is {_describe(value)}, not {expected.__name__}'
+
+
+def _mismatch_items(items, item_types, *, checker: Checker, path: str) -> str | None:
+    """Check each item of a sequence against its type."""
+    for index, (item, item_type) in enumerate(zip(items, item_types, strict=True)):
+        problem = mismatch(item, item_type, checker=checker, path=f'{path}[{index}]')
+        if problem is not None:
+            return problem
+    return None
+
+
+def _mismatch_tuple(value: tuple, expected: Any, *, checker: Checker, path: str) -> str | None:
+    """Check a tuple item by item, whether it is fixed or variadic."""
+    args = get_args(expected)
+    if len(args) == 2 and args[1] is Ellipsis:
+        return _mismatch_items(value, [args[0]] * len(value), checker=checker, path=path)
+    if args == ((),):
+        return None
+    # pycroscope has already matched the lengths.
+    return _mismatch_items(value, args, checker=checker, path=path)
+
+
+def _mismatch_mapping(value: dict, expected: Any, *, checker: Checker, path: str) -> str | None:
+    """Check a mapping key by key and value by value."""
+    key_type, value_type = get_args(expected) or (Any, Any)
+    for key, item in value.items():
+        problem = mismatch(key, key_type, checker=checker, path=f'{path} key {key!r}')
+        if problem is not None:
+            return problem
+        problem = mismatch(item, value_type, checker=checker, path=f'{path}[{key!r}]')
+        if problem is not None:
+            return problem
+    return None
+
+
+def _mismatch_array(value: Any, expected: Any, *, checker: Checker, path: str) -> str | None:
+    """Check an array as the array type it actually is.
+
+    A runtime array carries its dtype and shape, so unlike most generics its type
+    arguments can be recovered. pycroscope compares two array *types* argument by
+    argument, which it cannot do for the array itself.
+    """
+    numpy = sys.modules['numpy']
+    shape = tuple[()] if value.ndim == 0 else tuple[(int,) * value.ndim]  # type: ignore[misc]
+    actual = numpy.ndarray[shape, numpy.dtype[value.dtype.type]]
+    if _assignable(expected, type_from_runtime(actual), checker):
+        return None
+    return (
+        f'{path} is an array of dtype {value.dtype} with {value.ndim} dimension(s), '
+        f'which is not {expected}'
+    )
+
+
+def _is_array_type(expected: Any, ndarray: type) -> bool:
+    """Tell whether `expected` is a parametrised `ndarray`, also through `NDArray`.
+
+    `numpy.typing.NDArray` is a type alias, and on Python 3.12 and later a
+    subscripted alias reports the alias rather than `ndarray` as its origin.
+    """
+    origin = get_origin(expected)
+    aliased = getattr(origin, '__value__', None)
+    if aliased is not None:
+        origin = get_origin(aliased)
+    return origin is ndarray
+
+
+def _ndarray_class() -> type | None:
+    """Return `numpy.ndarray` if NumPy has been imported, without importing it."""
+    numpy = sys.modules.get('numpy')
+    return None if numpy is None else numpy.ndarray
+
+
+def _assignable(expected: Any, actual: Any, checker: Checker) -> bool:
+    """Ask pycroscope whether `actual`, a Value, is assignable to `expected`, a type."""
+    relation = has_relation(type_from_runtime(expected), actual, Relation.ASSIGNABLE, checker)
+    return not isinstance(relation, CanAssignError)
+
+
+def _describe(value: object) -> str:
+    """Name a value by its class and repr, the way the failure messages read."""
+    return f'{type(value).__name__} {value!r}'

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
 
-__commit_id__ = commit_id = 'g868a2293d'
+__commit_id__ = commit_id = 'gc60ea7172'

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert/plugin.py

@@ -46,9 +46,9 @@ def pytest_addoption(parser: pytest.Parser) -> None:
     parser.addini(
         CHECKERS_INI,
         'Type checkers to check the cases with, whitespace separated. Any of: '
-        'mypy, pyright. Each one gets a static test of its own per case, so a '
-        "case can be held to more than one checker's inference. Defaults to "
-        f'{" ".join(DEFAULT_CHECKERS)}.',
+        f'{", ".join(sorted(CHECKERS))}. Each one gets a static test of its own per '
+        "case, so a case can be held to more than one checker's inference. Defaults "
+        f'to {" ".join(DEFAULT_CHECKERS)}.',
         type='args',
         default=list(DEFAULT_CHECKERS),
     )
@@ -85,14 +85,34 @@ def cases_dir(config: pytest.Config) -> Path | None:
     return (Path(config.rootpath) / configured).resolve()
 
 
+def _is_case_file(file_path: Path, config: pytest.Config) -> bool:
+    """Tell whether `file_path` is a `.py` file in the configured cases directory."""
+    directory = cases_dir(config)
+    return directory is not None and file_path.suffix == '.py' and file_path.parent == directory
+
+
 def pytest_collect_file(file_path: Path, parent: pytest.Collector):
     """Collect a `.py` file in the configured cases directory as a case file."""
-    directory = cases_dir(parent.config)
-    if directory is None or file_path.suffix != '.py' or file_path.parent != directory:
+    # A path named on the command line reaches `pytest_pycollect_makemodule` below,
+    # which is where pytest's own Python collector would otherwise pick it up.
+    if not _is_case_file(file_path, parent.config) or parent.session.isinitpath(file_path):
         return None
     return CaseFileCollector.from_parent(parent, path=file_path)
 
 
+@pytest.hookimpl(tryfirst=True)
+def pytest_pycollect_makemodule(module_path: Path, parent: pytest.Collector):
+    """Collect a case file named on the command line as a case file, not a module.
+
+    pytest collects any `.py` path it is given explicitly as a test module whatever
+    its name, which would import the case file and run every assertion at import.
+    Answering this hook first hands the file to the case file collector instead.
+    """
+    if not _is_case_file(module_path, parent.config):
+        return None
+    return CaseFileCollector.from_parent(parent, path=module_path)
+
+
 def _diagnostics(config: pytest.Config, checker_name: str) -> dict[Path, list[Diagnostic]]:
     """Run one checker once per session and cache its result on the config."""
     cache = getattr(config, _DIAGNOSTICS, None)

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: type-assert
-Version: 0.1.0
+Version: 0.2.1
 Summary: pytest plugin that checks a value static type and its runtime type in one assertion
 Author: user27182
 License-Expression: MIT
@@ -122,6 +122,62 @@ it catches a `None` at any position in a `list[int]`, not only the first element
 
 Writing the type once covers both halves, and there is no way for them to drift apart.
 
+## What each half checks
+
+The checker's `assert_type` is exact: the inferred type must be the expected type, so
+`object` fails for an `int` and `list[float]` fails for a `list[int]`. The runtime
+check is assignability, the relation the type system itself uses for a value: an
+instance of a subclass passes for its base class, and every element of a container is
+held to the same rule.
+
+Two things are read more strictly than the type system would, because they are where a
+declared type and a produced value drift apart in practice:
+
+- A number has to be an instance of the numeric class named. An `int` does not pass for
+  `float`, a `bool` does not pass for `int`, and `[1, 2]` does not pass for
+  `list[float]`. A function that really returns either should say `float | int`.
+- A NumPy array is checked as the array type it actually is, dtype and number of
+  dimensions included, so a `float64` array does not pass for `NDArray[np.int64]`
+  and a 1-D array does not pass for `ndarray[tuple[int, int], ...]`.
+
+Both apply at any depth inside lists, tuples, sets and dicts. What the runtime half
+cannot check is a type argument the value does not carry: a `Box[int]` is only a `Box`
+at runtime, and there the checker is the sole authority. A supertype still fails only
+the static half, which is the intended division of labour: the checker guards what was
+declared, the run guards what was produced, and a case passes only when the declaration
+is exact and the value honours it.
+
+## Types that only a checker can spell
+
+Some types have no runtime spelling: a name imported under `TYPE_CHECKING`, or a class
+a checker treats as generic that cannot be subscripted at runtime, such as
+`np.dtype[np.generic[object]]`. Write the type as a string, the way an annotation can be
+quoted:
+
+```python
+assert_types(dtype_of(array), 'np.dtype[np.generic[object]]')
+```
+
+The checker reads the string as the type it names and holds the case to it exactly. At
+runtime the string is evaluated in the case file's namespace. When that succeeds the
+value is checked against it as usual, so a wrong quoted type still fails both halves.
+When the type cannot be built, the runtime half is skipped with the reason, since there
+is nothing to check the value against.
+
+To keep a runtime check as well, name the type under `TYPE_CHECKING` and give it a
+runtime stand-in:
+
+```python
+if TYPE_CHECKING:
+    DType = np.dtype[np.generic[object]]
+else:
+    DType = np.dtype
+
+assert_types(dtype_of(array), DType)
+```
+
+The checker still sees the exact type; the value is checked against the stand-in.
+
 ## Choosing a checker
 
 ```toml
@@ -163,6 +219,18 @@ after the file's setup has run, so making an entry conditional is ordinary Pytho
 entry naming an expression that no case makes fails the file's `setup` test, so a skip
 cannot quietly outlive the case it was written for.
 
+## Running the cases on their own
+
+Case files collect like any other test file, so a job can run just them:
+
+```bash
+pytest tests/typing/cases --no-cov
+```
+
+pytest-cov's `--no-cov` matters when the project sets a coverage threshold in
+`addopts`: the cases exercise only what they call, so `--cov-fail-under` would fail a
+run that is only about types. Runs of the whole suite are unaffected.
+
 ## License
 
 MIT

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ tools/check_without_checker.py
 type_assert/__init__.py
 type_assert/_assertions.py
 type_assert/_cases.py
+type_assert/_exact.py
 type_assert/_version.py
 type_assert/plugin.py
 type_assert/py.typed

{type_assert-0.1.0 → type_assert-0.2.1}/type_assert.egg-info/scm_file_list.json

@@ -22,6 +22,7 @@
     "type_assert/_checkers/_mypy.py",
     "type_assert/_checkers/_pyrefly.py",
     "type_assert/_checkers/_pyright.py",
+    "type_assert/_exact.py",
     "type_assert/plugin.py",
     "type_assert/py.typed"
   ]

type_assert-0.2.1/type_assert.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.2.1",
+  "distance": 0,
+  "node": "gc60ea7172b9c8d562dea6b21e1eb77e63352434f",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-05"
+}

type_assert-0.1.0/type_assert/_assertions.py

@@ -1,55 +0,0 @@
-"""The one assertion a typing case makes.
-
-To a type checker `assert_types` is `typing_extensions.assert_type`; at runtime it
-is a real checker. See the module body for why that works.
-"""
-
-from __future__ import annotations
-
-import functools
-from typing import TYPE_CHECKING
-from typing import Any
-
-if TYPE_CHECKING:
-    # A checker resolves an aliased import back to its original definition, so it
-    # applies its `assert_type` special case here: the inferred type must match
-    # `expected` *exactly*, not merely be assignable to it. Verified against both
-    # mypy and pyright. At runtime the definition below runs instead and checks the
-    # value, so one call covers both halves and they cannot drift apart.
-    from typing_extensions import assert_type as assert_types
-else:
-    from pycroscope.checker import Checker
-    from pycroscope.runtime import CanAssignError
-    from pycroscope.runtime import KnownValue
-    from pycroscope.runtime import Relation
-    from pycroscope.runtime import has_relation
-    from pycroscope.runtime import type_from_runtime
-
-    @functools.cache
-    def _checker() -> Checker:
-        """Return the shared checker, built on first use."""
-        return Checker()
-
-    def assert_types(value: object, expected: Any) -> object:
-        """Assert `value` is assignable to `expected` at runtime, and return it."""
-        # pycroscope's own `get_assignability_error` memoises against a module-global
-        # checker, which keeps every checked value alive for the rest of the session.
-        # Use our own so the memo can be dropped after each check.
-        checker = _checker()
-        try:
-            relation = has_relation(
-                type_from_runtime(expected), KnownValue(value), Relation.ASSIGNABLE, checker
-            )
-        finally:
-            cache = checker.get_relation_cache()
-            if cache is not None:
-                cache.clear()
-
-        if isinstance(relation, CanAssignError):
-            msg = (
-                f'Runtime value of type {type(value).__name__!r} is not assignable '
-                f'to the expected type:\n\t{expected}\n\n{relation.display(depth=0)}'
-            )
-            # An assertion that failed, not a caller passing the wrong kind of argument.
-            raise AssertionError(msg)  # noqa: TRY004
-        return value

type_assert-0.1.0/type_assert.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.0",
-  "distance": 0,
-  "node": "g868a2293d84b44102b054ea5a2fb75032a3ae317",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-31"
-}