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
