type-assert 0.1.0__py3-none-any.whl

type_assert/__init__.py

@@ -0,0 +1,27 @@
+"""Check a value's static type and its runtime type in one assertion.
+
+A case file is a stack of one-line `assert_types(expression, ExpectedType)` calls.
+A type checker checks the left of each pair against the right exactly; running the
+line checks the value the expression actually produces. The pytest plugin turns
+each line into two tests, so a disagreement between the two fails.
+"""
+
+from __future__ import annotations
+
+from ._assertions import assert_types as assert_types
+from ._cases import Case as Case
+from ._cases import CaseError as CaseError
+from ._cases import CaseFile as CaseFile
+from ._cases import CaseSkipped as CaseSkipped
+from ._cases import collect_case_file as collect_case_file
+from ._cases import collect_cases as collect_cases
+from ._checkers import CHECKERS as CHECKERS
+from ._checkers import Checker as Checker
+from ._checkers import CheckerError as CheckerError
+from ._checkers import Diagnostic as Diagnostic
+from ._checkers import get_checker as get_checker
+
+try:
+    from ._version import __version__ as __version__
+except ImportError:  # pragma: no cover - only when running from a source tree
+    __version__ = '0.0.0.dev0'

type_assert/_assertions.py

@@ -0,0 +1,55 @@
+"""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/_cases.py

@@ -0,0 +1,182 @@
+"""Split a case file into the setup it needs and the cases it declares."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from types import CodeType
+
+ASSERTION = 'assert_types'
+SKIP_RUNTIME = 'SKIP_RUNTIME'
+
+
+class CaseError(Exception):
+    """Raised when a case file is not shaped the way the framework expects."""
+
+
+class CaseSkipped(Exception):  # noqa: N818
+    """Raised instead of running a case the file asks to skip at runtime."""
+
+
+@dataclass(frozen=True)
+class Case:
+    """One `assert_types(expression, ExpectedType)` line."""
+
+    path: Path
+    lines: frozenset[int]
+    expression: str
+    expected: str
+    code: CodeType
+
+    @property
+    def id(self) -> str:
+        """Return the test id, which reads as the claim the case makes."""
+        return f'{self.expression} -> {self.expected}'
+
+
+@dataclass(frozen=True)
+class CaseFile:
+    """One case file: the cases it declares, and the setup they share."""
+
+    path: Path
+    cases: tuple[Case, ...]
+    setup_lines: frozenset[int]
+    setup_code: CodeType | None = None
+    error: str | None = None
+
+    @property
+    def name(self) -> str:
+        """Return the file name, used to scope test ids."""
+        return self.path.name
+
+    def setup_namespace(self) -> dict[str, Any]:
+        """Execute this file's setup and return the namespace it produced."""
+        namespace: dict[str, Any] = {'__name__': self.path.stem, '__file__': str(self.path)}
+        # Running the case file's own code is the point of the framework.
+        exec(self.setup_code, namespace)  # noqa: S102
+        return namespace
+
+    def run(self, case: Case) -> None:
+        """Execute one case, and only it, against a fresh copy of the setup.
+
+        Rebuilding the setup for every case is what keeps cases independent: one
+        cannot observe another's state, and reordering the file changes nothing.
+        """
+        namespace = self.setup_namespace()
+        reason = skip_reason(namespace, case)
+        if reason is not None:
+            raise CaseSkipped(reason)
+        exec(case.code, namespace)  # noqa: S102
+
+    def unknown_skips(self, namespace: dict[str, Any]) -> list[str]:
+        """Return `SKIP_RUNTIME` keys that match no case, so a stale one is caught."""
+        declared = namespace.get(SKIP_RUNTIME) or {}
+        expressions = {case.expression for case in self.cases}
+        return sorted(key for key in declared if key not in expressions)
+
+
+def skip_reason(namespace: dict[str, Any], case: Case) -> str | None:
+    """Return why `case` should not run, from the file's `SKIP_RUNTIME` mapping.
+
+    A case file maps an expression to the reason running it would fail — a
+    platform crash, an unavailable dependency. Mypy still checks the case, so
+    only the runtime half is skipped. Building the mapping conditionally is
+    ordinary Python, since it is read after the file's setup has run.
+    """
+    declared = namespace.get(SKIP_RUNTIME) or {}
+    return declared.get(case.expression) or 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):
+        return None
+    call = node.value
+    if not isinstance(call, ast.Call) or not isinstance(call.func, ast.Name):
+        return None
+    return call if call.func.id == ASSERTION else None
+
+
+def _reject_nested_assertions(tree: ast.Module, path: Path) -> None:
+    """Reject `assert_types` calls that are not statements at module level.
+
+    Such a call still type-checks, but it never becomes a case of its own, so it
+    would be silently left out of the runtime half.
+    """
+    top_level = {id(call) for call in map(_case_call, tree.body) if call is not None}
+    nested = [
+        node
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == ASSERTION
+        and id(node) not in top_level
+    ]
+    if nested:
+        lines = ', '.join(str(node.lineno) for node in nested)
+        msg = (
+            f'{path.name}: `{ASSERTION}` must be a statement at module level so that it '
+            f'becomes a case of its own. Found one nested at line(s) {lines}.'
+        )
+        raise CaseError(msg)
+
+
+def collect_case_file(path: Path) -> CaseFile:
+    """Parse one case file into its cases and the setup they share.
+
+    A file this cannot make sense of yields a `CaseFile` carrying the reason
+    rather than raising, so a malformed file fails its own test instead of
+    aborting collection for the session.
+    """
+    try:
+        return _parse_case_file(path)
+    except (CaseError, SyntaxError, OSError) as error:
+        return CaseFile(path=path, cases=(), setup_lines=frozenset(), error=str(error))
+
+
+def _parse_case_file(path: Path) -> CaseFile:
+    """Parse one case file, raising `CaseError` if it is not shaped as expected."""
+    source = path.read_text(encoding='utf-8')
+    tree = ast.parse(source, filename=str(path))
+    _reject_nested_assertions(tree, path)
+
+    setup = [node for node in tree.body if _case_call(node) is None]
+    setup_module = ast.Module(body=setup, type_ignores=[])
+    setup_code = compile(ast.fix_missing_locations(setup_module), str(path), 'exec')
+
+    cases = []
+    for node in tree.body:
+        call = _case_call(node)
+        if call is None:
+            continue
+        if len(call.args) != 2:
+            msg = f'{path.name}:{node.lineno}: `{ASSERTION}` takes an expression and a type.'
+            raise CaseError(msg)
+        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]),
+                code=compile(ast.fix_missing_locations(module), str(path), 'exec'),
+            )
+        )
+
+    case_lines = frozenset().union(*(case.lines for case in cases)) if cases else frozenset()
+    return CaseFile(
+        path=path,
+        cases=tuple(cases),
+        setup_lines=frozenset(range(1, len(source.splitlines()) + 1)) - case_lines,
+        setup_code=setup_code,
+    )
+
+
+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/_checkers/__init__.py

@@ -0,0 +1,43 @@
+"""Type checker backends, and the registry that selects one."""
+
+from __future__ import annotations
+
+from ._base import Checker
+from ._base import CheckerError
+from ._base import Diagnostic
+from ._mypy import MypyChecker
+from ._pyrefly import PyreflyChecker
+from ._pyright import PyrightChecker
+
+__all__ = [
+    'CHECKERS',
+    'Checker',
+    'CheckerError',
+    'Diagnostic',
+    'MypyChecker',
+    'PyreflyChecker',
+    'PyrightChecker',
+    'get_checker',
+]
+
+#: Every checker that can be selected, by name.
+#:
+#: `ty` is deliberately absent: it is pre-1.0 and its output format is still moving,
+#: so supporting it would mean tracking those changes. Adding a backend is one module
+#: implementing `Checker` plus an entry here.
+CHECKERS: dict[str, type[Checker]] = {
+    MypyChecker.name: MypyChecker,
+    PyreflyChecker.name: PyreflyChecker,
+    PyrightChecker.name: PyrightChecker,
+}
+
+
+def get_checker(name: str) -> Checker:
+    """Return the checker called `name`."""
+    try:
+        checker = CHECKERS[name]
+    except KeyError:
+        known = ', '.join(sorted(CHECKERS))
+        msg = f'Unknown type checker {name!r}. Available: {known}.'
+        raise CheckerError(msg) from None
+    return checker()

type_assert/_checkers/_base.py

@@ -0,0 +1,54 @@
+"""What every type checker backend has to provide."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+class CheckerError(Exception):
+    """Raised when a checker could not run, as opposed to reporting diagnostics."""
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One error a checker reported, at one line of one file."""
+
+    path: Path
+    line: int
+    message: str
+
+
+class Checker:
+    """Runs a type checker over a package and returns its errors keyed by file.
+
+    Subclasses supply the command to run and how to read its output. Both run the
+    checker in a separate process, so a crash surfaces as a failed call rather
+    than taking the test session down with it.
+    """
+
+    #: Name this checker is selected by.
+    name: str
+    #: Distribution to install to get it, when it is missing.
+    distribution: str
+
+    def run(
+        self,
+        package: str,
+        *,
+        root: Path,
+        cache_dir: Path | None,
+        extra_args: Sequence[str] = (),
+    ) -> dict[Path, list[Diagnostic]]:
+        """Type-check `package` from `root` and return its errors keyed by file.
+
+        Running from `root` is what makes the project's own checker configuration
+        apply, since that is where every checker looks for it. `extra_args` covers
+        what the configuration cannot say: a different config file, a Python
+        version, a strictness flag.
+        """
+        raise NotImplementedError

type_assert/_checkers/_mypy.py

@@ -0,0 +1,86 @@
+"""The mypy backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+from ._base import Checker
+from ._base import CheckerError
+from ._base import Diagnostic
+
+# `path:line:col: severity: message`, with the column absent on whole-file diagnostics.
+_DIAGNOSTIC = re.compile(r'^(?P<path>.+?):(?P<line>\d+):(?:\d+:)? (?P<severity>\w+): (?P<msg>.*)$')
+
+
+class MypyChecker(Checker):
+    """Runs mypy and reads its text output."""
+
+    name = 'mypy'
+    distribution = 'mypy'
+
+    def run(
+        self,
+        package: str,
+        *,
+        root: Path,
+        cache_dir: Path | None,
+        extra_args: Sequence[str] = (),
+    ) -> dict[Path, list[Diagnostic]]:
+        """Type-check `package` from `root` and return mypy's errors keyed by file.
+
+        mypy discovers the project's own configuration from `root`, so nothing has
+        to be restated here. Anything it cannot express goes in `extra_args`.
+        """
+        # `--follow-imports=silent` types the symbols the cases use without reporting
+        # the host project's own diagnostics, which vary by platform and dependency
+        # versions and have nothing to do with the cases. It comes before `extra_args`
+        # so a project that wants a different setting can say so.
+        defaults = ['--follow-imports=silent']
+        if cache_dir is not None:
+            defaults.append(f'--cache-dir={cache_dir}')
+        # These come after, because the output is parsed and has to stay parsable.
+        required = ['--no-color-output', '--no-error-summary', '--no-pretty', '--show-traceback']
+        args = [
+            sys.executable,
+            '-m',
+            'mypy',
+            *defaults,
+            *extra_args,
+            *required,
+            '--package',
+            package,
+        ]
+
+        try:
+            process = subprocess.run(args, capture_output=True, cwd=root, text=True, check=False)
+        except OSError as error:  # pragma: no cover - defensive
+            msg = f'Could not run mypy: {error}'
+            raise CheckerError(msg) from error
+
+        # mypy exits 1 when it reports diagnostics and 2 when it could not run.
+        if process.returncode > 1 or process.stderr:
+            hint = ''
+            if 'No module named mypy' in process.stderr:
+                hint = '\n\nInstall it with: pip install type-assert[mypy]'
+            msg = (
+                f'mypy failed to run:\n{" ".join(args)}\n\n{process.stderr}{process.stdout}{hint}'
+            )
+            raise CheckerError(msg)
+
+        diagnostics: dict[Path, list[Diagnostic]] = {}
+        for line in process.stdout.splitlines():
+            match = _DIAGNOSTIC.match(line)
+            if match is None or match['severity'] != 'error':
+                continue
+            path = (Path(root) / match['path']).resolve()
+            diagnostics.setdefault(path, []).append(
+                Diagnostic(path=path, line=int(match['line']), message=match['msg'])
+            )
+        return diagnostics

type_assert/_checkers/_pyrefly.py

@@ -0,0 +1,100 @@
+"""The pyrefly backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+from ._base import Checker
+from ._base import CheckerError
+from ._base import Diagnostic
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# `ERROR path:line:col-col: message`, the shape of `--output-format min-text`.
+_DIAGNOSTIC = re.compile(r'^ERROR (?P<path>.+?):(?P<line>\d+):\d+(?:-\d+)?: (?P<msg>.*)$')
+
+# pyrefly says this, then checks nothing at all and reports success.
+_NO_CONFIG = 'No `pyrefly.toml` found'
+
+
+class PyreflyChecker(Checker):
+    """Runs pyrefly and reads its one-line-per-error output."""
+
+    name = 'pyrefly'
+    distribution = 'pyrefly'
+
+    def run(
+        self,
+        package: str,
+        *,
+        root: Path,
+        cache_dir: Path | None,
+        extra_args: Sequence[str] = (),
+    ) -> dict[Path, list[Diagnostic]]:
+        """Type-check `package` from `root` and return pyrefly's errors keyed by file.
+
+        pyrefly discovers the project's own configuration from `root`, and unlike
+        the others it will not check anything without one -- see below.
+        """
+        del cache_dir  # pyrefly keeps no cache of its own to point elsewhere.
+        target = Path(root) / Path(*package.split('.'))
+        # pyrefly reports success for a path that does not exist, where mypy and
+        # pyright both refuse. Refuse here too: passing for nothing is the one
+        # outcome a checker must never produce.
+        if not target.exists():
+            msg = f'pyrefly was asked to check {target}, which does not exist.'
+            raise CheckerError(msg)
+        args = [
+            sys.executable,
+            '-m',
+            'pyrefly',
+            'check',
+            '--python-interpreter-path',
+            sys.executable,
+            *extra_args,
+            # Last, because the output is parsed and has to stay parsable.
+            '--output-format',
+            'min-text',
+            str(target),
+        ]
+
+        try:
+            process = subprocess.run(args, capture_output=True, cwd=root, text=True, check=False)
+        except OSError as error:  # pragma: no cover - defensive
+            msg = f'Could not run pyrefly: {error}'
+            raise CheckerError(msg) from error
+
+        output = process.stdout + process.stderr
+        if 'No module named pyrefly' in process.stderr:
+            msg = (
+                f'pyrefly failed to run:\n{" ".join(args)}\n\n{output}\n\n'
+                f'Install it with: pip install type-assert[pyrefly]'
+            )
+            raise CheckerError(msg)
+
+        # Without a config pyrefly ignores the paths it is given and reports success,
+        # which would silently pass every case. Refuse rather than pass for nothing.
+        if _NO_CONFIG in output:
+            msg = (
+                'pyrefly found no configuration and so checked nothing, which would '
+                'pass every case without looking at it. Give the project a '
+                '`pyrefly.toml`, or a `[tool.pyrefly]` table in `pyproject.toml`, '
+                f'naming the cases directory in `project-includes`.\n\n{output}'
+            )
+            raise CheckerError(msg)
+
+        diagnostics: dict[Path, list[Diagnostic]] = {}
+        for line in output.splitlines():
+            match = _DIAGNOSTIC.match(line.strip())
+            if match is None:
+                continue
+            path = (Path(root) / match['path']).resolve()
+            diagnostics.setdefault(path, []).append(
+                Diagnostic(path=path, line=int(match['line']), message=match['msg'])
+            )
+        return diagnostics

type_assert/_checkers/_pyright.py

@@ -0,0 +1,97 @@
+"""The pyright backend."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+from ._base import Checker
+from ._base import CheckerError
+from ._base import Diagnostic
+
+
+def _extract_report(stdout: str) -> dict | None:
+    """Return the JSON report from pyright's output, or `None` if there is none.
+
+    The `pyright` distribution downloads its own copy of node on first use and
+    announces it on stdout, so the report is not always the whole of it.
+    """
+    for start, line in enumerate(stdout.splitlines(keepends=True)):
+        if line.startswith('{'):
+            offset = sum(len(previous) for previous in stdout.splitlines(keepends=True)[:start])
+            try:
+                return json.loads(stdout[offset:])
+            except json.JSONDecodeError:
+                continue
+    return None
+
+
+class PyrightChecker(Checker):
+    """Runs pyright and reads its JSON output."""
+
+    name = 'pyright'
+    distribution = 'pyright'
+
+    def run(
+        self,
+        package: str,
+        *,
+        root: Path,
+        cache_dir: Path | None,
+        extra_args: Sequence[str] = (),
+    ) -> dict[Path, list[Diagnostic]]:
+        """Type-check `package` from `root` and return pyright's errors keyed by file.
+
+        pyright discovers the project's own configuration from `root`, so nothing
+        has to be restated here. Anything it cannot express goes in `extra_args`.
+        """
+        del cache_dir  # pyright keeps no cache of its own to point elsewhere.
+        # pyright reports only on the files it is given, so unlike mypy it needs no
+        # equivalent of `--follow-imports=silent` to stay quiet about the host project.
+        target = Path(root) / Path(*package.split('.'))
+        args = [
+            sys.executable,
+            '-m',
+            'pyright',
+            '--pythonpath',
+            sys.executable,
+            *extra_args,
+            # Last, because the output is parsed and has to stay parsable.
+            '--outputjson',
+            str(target),
+        ]
+
+        try:
+            process = subprocess.run(args, capture_output=True, cwd=root, text=True, check=False)
+        except OSError as error:  # pragma: no cover - defensive
+            msg = f'Could not run pyright: {error}'
+            raise CheckerError(msg) from error
+
+        report = _extract_report(process.stdout)
+        if report is None:
+            hint = ''
+            if 'No module named pyright' in process.stderr:
+                hint = '\n\nInstall it with: pip install type-assert[pyright]'
+            msg = (
+                f'pyright failed to run:\n{" ".join(args)}\n\n'
+                f'{process.stderr}{process.stdout}{hint}'
+            )
+            raise CheckerError(msg)
+
+        diagnostics: dict[Path, list[Diagnostic]] = {}
+        for entry in report.get('generalDiagnostics', []):
+            if entry.get('severity') != 'error':
+                continue
+            path = Path(entry['file']).resolve()
+            # pyright counts lines from zero; everything else here counts from one.
+            line = entry['range']['start']['line'] + 1
+            diagnostics.setdefault(path, []).append(
+                Diagnostic(path=path, line=line, message=entry['message'].replace('\n', ' '))
+            )
+        return diagnostics

type_assert/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = 'g868a2293d'

type_assert/plugin.py

@@ -0,0 +1,227 @@
+"""Pytest integration: collect case files and run each case as its own test.
+
+Registered as a pytest plugin by entry point, so a project only has to say where
+its cases live::
+
+    [tool.pytest.ini_options]
+    type_assert_cases = 'tests/typing/cases'
+    type_assert_checkers = 'mypy pyright'
+
+Each case file then collects as a test file of its own: one `setup` test for the
+lines that are not cases, one runtime test per case, and one static test per case
+per configured checker.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from ._cases import CaseSkipped
+from ._cases import collect_case_file
+from ._checkers import CHECKERS
+from ._checkers import get_checker
+
+if TYPE_CHECKING:
+    from ._cases import Case
+    from ._cases import CaseFile
+    from ._checkers import Diagnostic
+
+CASES_INI = 'type_assert_cases'
+CHECKERS_INI = 'type_assert_checkers'
+DEFAULT_CHECKERS = ('mypy',)
+
+_DIAGNOSTICS = '_type_assert_diagnostics'
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register the settings a project needs."""
+    parser.addini(
+        CASES_INI,
+        'Directory of type_assert case files, relative to the rootdir.',
+        default='',
+    )
+    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)}.',
+        type='args',
+        default=list(DEFAULT_CHECKERS),
+    )
+    # One per registered checker, since their flags have nothing in common. Each
+    # checker already reads the project's own configuration -- it runs from the
+    # rootdir, which is where every checker looks -- so this is for what that
+    # configuration cannot say: a different config file, a Python version, a
+    # strictness flag that should apply to the cases and nothing else.
+    for name in sorted(CHECKERS):
+        parser.addini(
+            checker_args_ini(name),
+            f'Extra command line arguments for {name}, whitespace separated.',
+            type='args',
+            default=[],
+        )
+
+
+def checker_args_ini(checker_name: str) -> str:
+    """Return the ini option holding extra arguments for `checker_name`."""
+    return f'type_assert_{checker_name}_args'
+
+
+def configured_checkers(config: pytest.Config) -> list[str]:
+    """Return the names of the checkers the cases are checked with."""
+    names = [str(name) for name in config.getini(CHECKERS_INI) if str(name).strip()]
+    return names or list(DEFAULT_CHECKERS)
+
+
+def cases_dir(config: pytest.Config) -> Path | None:
+    """Return the configured cases directory, or `None` when unset."""
+    configured = str(config.getini(CASES_INI)).strip()
+    if not configured:
+        return None
+    return (Path(config.rootpath) / configured).resolve()
+
+
+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:
+        return None
+    return CaseFileCollector.from_parent(parent, path=file_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)
+    if cache is None:
+        cache = {}
+        setattr(config, _DIAGNOSTICS, cache)
+    if checker_name not in cache:
+        directory = cases_dir(config)
+        assert directory is not None  # only reachable from a collected case file
+        root = Path(config.rootpath)
+        checker = get_checker(checker_name)
+        # A cache directory per checker and per xdist worker: the run is cheap once
+        # warm, and sharing one between concurrent workers is what makes it stale.
+        worker = getattr(config, 'workerinput', {}).get('workerid', 'master')
+        cache[checker_name] = checker.run(
+            '.'.join(directory.relative_to(root).parts),
+            root=root,
+            cache_dir=root / '.mypy_cache' / f'type_assert-{checker_name}-{worker}',
+            extra_args=[str(arg) for arg in config.getini(checker_args_ini(checker_name))],
+        )
+    return cache[checker_name]
+
+
+def _report(case_file: CaseFile, checker_name: str, errors: list[Diagnostic]) -> str:
+    """Return the checker's messages against the source lines they came from."""
+    source = case_file.path.read_text(encoding='utf-8').splitlines()
+    body = '\n'.join(
+        f'{case_file.name}:{error.line}: {error.message}\n\t{source[error.line - 1].strip()}'
+        for error in errors
+    )
+    return f'{checker_name} reported {len(errors)} error(s):\n{body}'
+
+
+class CaseFileCollector(pytest.File):
+    """Collects one case file as a test file."""
+
+    def collect(self):
+        """Yield the file's setup test, and per case a runtime test and a static one."""
+        case_file = collect_case_file(Path(self.path))
+        checkers = configured_checkers(self.config)
+        yield SetupItem.from_parent(self, name='setup', case_file=case_file)
+        for case in case_file.cases:
+            yield RuntimeItem.from_parent(
+                self, name=f'{case.id} [runtime]', case_file=case_file, case=case
+            )
+            for checker_name in checkers:
+                yield StaticItem.from_parent(
+                    self,
+                    name=f'{case.id} [static: {checker_name}]',
+                    case_file=case_file,
+                    case=case,
+                    checker_name=checker_name,
+                )
+
+
+class _Item(pytest.Item):
+    """Shared plumbing for the tests a case file collects."""
+
+    def __init__(self, *args, case_file: CaseFile, **kwargs) -> None:
+        """Record the case file this test belongs to."""
+        super().__init__(*args, **kwargs)
+        self.case_file = case_file
+
+    def reportinfo(self):
+        """Locate this test in its case file."""
+        return self.path, None, self.name
+
+    def errors_on(self, checker_name: str, lines: frozenset[int]) -> list[Diagnostic]:
+        """Return one checker's errors falling on `lines` of this case file."""
+        reported = _diagnostics(self.config, checker_name).get(self.case_file.path.resolve(), [])
+        return [diagnostic for diagnostic in reported if diagnostic.line in lines]
+
+
+class SetupItem(_Item):
+    """Checks a case file's setup: that it is well formed, runs, and type-checks."""
+
+    def runtest(self) -> None:
+        """Assert the file parses, its setup executes, and nothing else is wrong."""
+        # Report the file's own problem before asking for a type-check of it: a file
+        # the checker cannot parse fails the whole run, which would mask the reason.
+        if self.case_file.error is not None:
+            pytest.fail(self.case_file.error, pytrace=False)
+
+        namespace = self.case_file.setup_namespace()
+        unknown = self.case_file.unknown_skips(namespace)
+        if unknown:
+            listed = '\n'.join(f'  {key}' for key in unknown)
+            pytest.fail(
+                f'SKIP_RUNTIME names expressions that no case in this file makes, so the '
+                f'skip no longer applies to anything:\n{listed}',
+                pytrace=False,
+            )
+
+        for checker_name in configured_checkers(self.config):
+            errors = self.errors_on(checker_name, self.case_file.setup_lines)
+            if errors:
+                pytest.fail(_report(self.case_file, checker_name, errors), pytrace=False)
+
+
+class _CaseItem(_Item):
+    """A test about one case."""
+
+    def __init__(self, *args, case: Case, **kwargs) -> None:
+        """Record the case this test is about."""
+        super().__init__(*args, **kwargs)
+        self.case = case
+
+
+class RuntimeItem(_CaseItem):
+    """Checks the value a case builds against the type the case expects."""
+
+    def runtest(self) -> None:
+        """Run this case, and only it."""
+        try:
+            self.case_file.run(self.case)
+        except CaseSkipped as skipped:
+            pytest.skip(str(skipped))
+
+
+class StaticItem(_CaseItem):
+    """Checks the type one checker infers for a case against the type it expects."""
+
+    def __init__(self, *args, checker_name: str, **kwargs) -> None:
+        """Record which checker this test speaks for."""
+        super().__init__(*args, **kwargs)
+        self.checker_name = checker_name
+
+    def runtest(self) -> None:
+        """Assert the checker reports nothing on this case's lines."""
+        errors = self.errors_on(self.checker_name, self.case.lines)
+        if errors:
+            pytest.fail(_report(self.case_file, self.checker_name, errors), pytrace=False)

type_assert-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: type-assert
+Version: 0.1.0
+Summary: pytest plugin that checks a value static type and its runtime type in one assertion
+Author: user27182
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/user27182/type-assert
+Project-URL: Issues, https://github.com/user27182/type-assert/issues
+Keywords: annotations,mypy,pyright,pytest,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycroscope<0.6,>=0.5
+Requires-Dist: pytest>=7
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: all
+Requires-Dist: type-assert[mypy,pyrefly,pyright]; extra == "all"
+Provides-Extra: mypy
+Requires-Dist: mypy>=1.11; extra == "mypy"
+Provides-Extra: pyrefly
+Requires-Dist: pyrefly>=1.0; extra == "pyrefly"
+Provides-Extra: pyright
+Requires-Dist: pyright>=1.1.390; extra == "pyright"
+Dynamic: license-file
+
+# type-assert
+
+pytest plugin that checks a value's static type and its runtime type in one assertion.
+
+A type checker only ever sees the annotations. A runtime checker only ever sees the
+values. Either can be right while the other is wrong, and overloaded signatures are
+where they drift apart. `type-assert` pins both halves at once, from one line:
+
+```python
+assert_types(json.loads('[1]'), Any)
+assert_types(sorted({'b', 'a'}), list[str])
+```
+
+Each line becomes two tests. One runs the expression and checks the value it produced.
+The other checks what a type checker inferred for the same line. The line only passes
+if the two agree.
+
+> **Warning** — The API of this package is unstable and likely to change between
+> minor versions (for example `0.1.0` to `0.2.0`). Pin the exact version you
+> depend on, for example `type-assert==0.1.0`.
+
+## Installation
+
+```bash
+pip install type-assert[mypy]     # or [pyright], [pyrefly], or [all]
+```
+
+The checker itself is an extra, because it should be whichever one your project
+already uses.
+
+## Usage
+
+Put a directory of case files somewhere in your test tree and point the plugin at it:
+
+```toml
+[tool.pytest.ini_options]
+type_assert_cases = 'tests/typing/cases'
+```
+
+A case file is an ordinary Python module. Every top-level `assert_types` call is a case;
+everything else — imports, helpers, constants — is setup shared by the cases in that
+file:
+
+```python
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from type_assert import assert_types
+
+
+def payload() -> str:
+    """Return a document to parse."""
+    return '{"a": 1}'
+
+
+assert_types(json.loads(payload()), Any)
+assert_types(sorted({'b', 'a'}), list[str])
+assert_types(''.join([]), str)
+```
+
+Running pytest collects each case file as a test file of its own:
+
+```text
+tests/typing/cases/basics.py::setup
+tests/typing/cases/basics.py::sorted({'b', 'a'}) -> list[str] [runtime]
+tests/typing/cases/basics.py::sorted({'b', 'a'}) -> list[str] [static]
+```
+
+## How `assert_types` does both
+
+To a type checker, `assert_types` *is*
+[`typing_extensions.assert_type`](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.assert_type),
+aliased under `TYPE_CHECKING`. Checkers resolve an aliased import back to its original
+definition, so the special case still applies: the inferred type must match the second
+argument **exactly**, and a supertype is a failure rather than a pass.
+
+At runtime that name is bound to a real checker instead, backed by
+[pycroscope](https://pycroscope.readthedocs.io/), which walks containers exhaustively —
+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.
+
+## Choosing a checker
+
+```toml
+[tool.pytest.ini_options]
+type_assert_checkers = 'mypy'                   # the default
+type_assert_checkers = 'pyright'
+type_assert_checkers = 'mypy pyright pyrefly'   # each with its own test
+```
+
+Naming more than one gives every case a static test per checker, so a case has to hold
+under all of them:
+
+```text
+cases/basics.py::sorted({'b', 'a'}) -> list[str] [runtime]
+cases/basics.py::sorted({'b', 'a'}) -> list[str] [static: mypy]
+cases/basics.py::sorted({'b', 'a'}) -> list[str] [static: pyright]
+```
+
+The runtime test is not repeated, since the value does not depend on who checked it.
+Bear in mind that two checkers do not always infer the same type for the same
+expression, so a case that satisfies one may need rewording to satisfy both.
+
+`ty` is deliberately not supported yet: it is pre-1.0 and its output format is still
+moving. Adding a backend is a single module — see `type_assert/_checkers/`.
+
+## Skipping a case at runtime
+
+A case that cannot run everywhere — it crashes on a platform, or needs something that is
+not always installed — is named in a `SKIP_RUNTIME` mapping in its own file:
+
+```python
+SKIP_RUNTIME = {
+    'expression exactly as written': 'why running it fails here',
+}
+```
+
+Only the runtime half is skipped; the checker still checks the case. The mapping is read
+after the file's setup has run, so making an entry conditional is ordinary Python. An
+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.
+
+## License
+
+MIT

type_assert-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+type_assert/__init__.py,sha256=FuZcdyVFXVPBO2RJk8tvTr0k3DpQlx3wGkaOWcW2tPE,1158
+type_assert/_assertions.py,sha256=M1DnFu7p7UQpsyGLMha24Vdum0GRYWqOCvLLnD08Bzw,2331
+type_assert/_cases.py,sha256=U_eOGHhegkqt66S6TFrZrWFissdwqEOJIr_fNga9L8c,6570
+type_assert/_version.py,sha256=DAfDHBn0nskQX4XfJFqp5cZl3BnPTKK40xEbsCjp0-o,528
+type_assert/plugin.py,sha256=XcP_TvV9ToS9_KtjbLBNu5yTS9hLQMQQoHRUhW7odBk,8886
+type_assert/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+type_assert/_checkers/__init__.py,sha256=OlLu4fy1A5FyxB_noPqjhkIsUyOGWmhra1QqQuxYtD8,1211
+type_assert/_checkers/_base.py,sha256=a_1j88gWylAfdlsHS6G9S2IYInnxzRvyD8HFGdSaQqo,1572
+type_assert/_checkers/_mypy.py,sha256=bUV40-8CbRJkrOXMfQvj53UcL-SX4Rix60qNrlnBNeY,3124
+type_assert/_checkers/_pyrefly.py,sha256=dLWxnDxywv_l6xYngZowZPDCvbpzXUyah5XA01YBE2g,3683
+type_assert/_checkers/_pyright.py,sha256=IomrJzqKMb6dItI2fbOHdAUo31CA6D47Z_onHSkaK8E,3427
+type_assert-0.1.0.dist-info/licenses/LICENSE,sha256=8NfcALclfVO78lnzIfZVRlCn2rNGBfs1EFyHKF7gvfM,1070
+type_assert-0.1.0.dist-info/METADATA,sha256=_YITpK_vjl0oC0rjh-0OQ9Rk0Thj6UxT4KPuFzW0wT0,5913
+type_assert-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+type_assert-0.1.0.dist-info/entry_points.txt,sha256=7HmS--0q4AtdGVGlBbP-ZnYk3TV7C9YMP0TW1TZdscM,44
+type_assert-0.1.0.dist-info/top_level.txt,sha256=yzHvUttBFBti_BE8_lMgvZ7rblwz2p49SbhN6gc9dMU,12
+type_assert-0.1.0.dist-info/RECORD,,

type_assert-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

type_assert-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+type_assert = type_assert.plugin

type_assert-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2026 user27182
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

type_assert-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+type_assert