type-assert 0.1.0__tar.gz

type_assert-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: /
+  schedule:
+    interval: weekly
+  labels: [maintenance, dependencies]
+  open-pull-requests-limit: 20
+- package-ecosystem: github-actions
+  directory: /.github/workflows
+  schedule:
+    interval: weekly
+  labels: [maintenance, dependencies]
+  groups:
+    artifacts:
+      patterns: [actions/upload-artifact, actions/download-artifact]

type_assert-0.1.0/.github/release.yml

@@ -0,0 +1,9 @@
+changelog:
+  exclude:
+    authors:
+    - dependabot
+    - dependabot[bot]
+    - pre-commit-ci
+    - pre-commit-ci[bot]
+    - github-actions
+    - github-actions[bot]

type_assert-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+# `pull_request` is deliberately unfiltered: filtering it by base branch would
+# skip every pull request in a stack that does not target main.
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d   # v10.0.1
+      with:
+        enable-cache: false
+    - run: uv sync --group dev
+    - run: uv run pre-commit run --all-files --show-diff-on-failure
+      env:
+          # This hook exists to stop *local* commits straight to main; it
+          # would always fail here since CI checks out that branch/tag directly.
+        SKIP: no-commit-to-branch
+
+  test:
+      # Every supported Python, on every platform: the plugin shells out to a
+      # checker and parses its output, which is exactly where paths differ.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d   # v10.0.1
+      with:
+        enable-cache: false
+    - run: uv sync --group dev --extra all --python ${{ matrix.python-version }}
+      # Coverage has to start before pytest, since the plugin is imported by
+      # entry point before any pytest-cov hook would run.
+    - run: uv run coverage run -m pytest
+    - run: uv run coverage combine
+    - run: uv run coverage report --fail-under=95
+    - run: uv run coverage xml
+    - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f   # v7.0.0
+      if: matrix.os == 'ubuntu-latest'
+      with:
+        files: ./coverage.xml
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  test-no-checker:
+      # Neither checker is a hard dependency. With neither installed the package
+      # must still import and the runtime half must still work; only the static
+      # half is unavailable, and it has to say so plainly.
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d   # v10.0.1
+      with:
+        enable-cache: false
+    - run: uv sync --no-dev
+    - run: uv run --no-sync python tools/check_without_checker.py
+
+  build:
+    needs: [pre-commit, test]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d   # v10.0.1
+      with:
+        enable-cache: false
+    - run: uv build
+    - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a   # v7.0.1
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c   # v8.0.1
+      with:
+        name: dist
+        path: dist/
+    - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33   # release/v1

type_assert-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.coverage
+.coverage.*
+.idea/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+type_assert/_version.py
+uv.lock

type_assert-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+ci:
+  autoupdate_commit_msg: 'chore: update pre-commit hooks'
+  autofix_prs: true
+  autoupdate_schedule: quarterly
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: check-merge-conflict
+  - id: debug-statements
+  - id: no-commit-to-branch
+    args: [--branch, main]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.16.0
+  hooks:
+  - id: ruff-check
+    args: [--fix, --show-fixes]
+  - id: ruff-format
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.11.0
+  hooks:
+  - id: zizmor
+
+- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+  rev: v2.15.0
+  hooks:
+  - id: pretty-format-yaml
+    args: [--autofix, --indent, '2']
+
+- repo: https://github.com/ComPWA/taplo-pre-commit
+  rev: v0.9.3
+  hooks:
+  - id: taplo-format
+      # See options: https://taplo.tamasfe.dev/configuration/formatter-options.html
+    args: [--option, reorder_arrays=true, --option, reorder_keys=true, --option, align_comments=false]

type_assert-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,128 @@
+# 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/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+build-backend = 'setuptools.build_meta'
+requires = ['setuptools>=64', 'setuptools_scm>=8']
+
+[dependency-groups]
+dev = ['pre-commit', 'pytest-cov', { include-group = 'test' }]
+test = ['mypy', 'pyrefly', 'pyright', 'pytest']
+
+[project]
+authors = [{ name = 'user27182' }]
+classifiers = [
+  'Development Status :: 3 - Alpha',
+  'Framework :: Pytest',
+  'Intended Audience :: Developers',
+  'Operating System :: MacOS',
+  'Operating System :: Microsoft :: Windows',
+  'Operating System :: POSIX :: Linux',
+  'Programming Language :: Python :: 3',
+  'Programming Language :: Python :: 3.10',
+  'Programming Language :: Python :: 3.11',
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: 3.14',
+  'Topic :: Software Development :: Quality Assurance',
+  'Topic :: Software Development :: Testing',
+  'Typing :: Typed',
+]
+dependencies = ['pycroscope>=0.5,<0.6', 'pytest>=7', 'typing-extensions>=4.5']
+description = 'pytest plugin that checks a value static type and its runtime type in one assertion'
+dynamic = ['version']
+keywords = ['annotations', 'mypy', 'pyright', 'pytest', 'typing']
+license = 'MIT'
+name = 'type-assert'
+readme = 'README.md'
+requires-python = '>=3.10'
+
+[project.entry-points.pytest11]
+type_assert = 'type_assert.plugin'
+
+[project.optional-dependencies]
+# A checker is whatever the project under test already uses; neither is required.
+all = ['type-assert[mypy,pyrefly,pyright]']
+mypy = ['mypy>=1.11']
+pyrefly = ['pyrefly>=1.0']
+pyright = ['pyright>=1.1.390']
+
+[project.urls]
+Homepage = 'https://github.com/user27182/type-assert'
+Issues = 'https://github.com/user27182/type-assert/issues'
+
+[tool.coverage.run]
+branch = true
+omit = ['*/_version.py']
+parallel = true
+source = ['type_assert']
+
+[tool.pytest.ini_options]
+addopts = '--strict-config --strict-markers'
+testpaths = 'tests'
+
+[tool.ruff]
+indent-width = 4
+line-length = 99
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 75
+quote-style = 'single'
+
+[tool.ruff.lint]
+extend-select = [
+  'A',
+  'B',
+  'C4',
+  'D',
+  'E',
+  'EM',
+  'F',
+  'FA',
+  'I',
+  'ICN',
+  'N',
+  'PERF',
+  'PGH',
+  'PIE',
+  'PT',
+  'RET',
+  'RSE',
+  'RUF',
+  'SIM',
+  'T10',
+  'T20',
+  'TCH',
+  'TID',
+  'UP',
+  'W',
+  'YTT',
+]
+ignore = ['D203', 'D211', 'D213']
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-single-line = true
+force-sort-within-sections = true
+required-imports = ['from __future__ import annotations']
+
+[tool.ruff.lint.per-file-ignores]
+'tests/*' = ['D102', 'D103']
+# `Union` and `Optional` here are runtime values handed to `assert_types`, not
+# annotations. Both spellings are worth covering, since users write both.
+'tests/test_assertions.py' = ['D102', 'D103', 'UP007', 'UP045']
+
+[tool.ruff.lint.pyupgrade]
+keep-runtime-typing = true
+
+[tool.setuptools]
+license-files = ['LICENSE']
+packages = ['type_assert', 'type_assert._checkers']
+
+[tool.setuptools.package-data]
+type_assert = ['py.typed']
+
+[tool.setuptools_scm]
+version_scheme = 'release-branch-semver'
+write_to = 'type_assert/_version.py'

type_assert-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

type_assert-0.1.0/tests/conftest.py

@@ -0,0 +1,37 @@
+"""Shared fixtures for the test suite."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+pytest_plugins = ['pytester']
+
+REPO_ROOT = Path(__file__).parent.parent
+
+
+@pytest.fixture
+def checker_root(tmp_path, monkeypatch):
+    """Return a project root the checkers can resolve `type_assert` from.
+
+    The project installs itself editable through an import finder, which neither
+    mypy nor pyright can follow, so point both at the source tree instead. This is
+    a fact about developing this package: an ordinary installation puts `type_assert`
+    in site-packages, where both find it with no help.
+    """
+    monkeypatch.setenv('MYPYPATH', str(REPO_ROOT))
+    (tmp_path / 'pyrightconfig.json').write_text(
+        json.dumps({'extraPaths': [str(REPO_ROOT)]}), encoding='utf-8'
+    )
+    write_pyrefly_config(tmp_path)
+    return tmp_path
+
+
+def write_pyrefly_config(directory):
+    """Give `directory` a pyrefly config, which pyrefly refuses to work without."""
+    (directory / 'pyrefly.toml').write_text(
+        f'project-includes = ["cases"]\nsearch-path = [{str(REPO_ROOT)!r}]\n',
+        encoding='utf-8',
+    )