subtype 0.1.0__tar.gz

subtype-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+# python sources
+*.py    text diff=python
+
+# documents
+*.md    text diff=markdown
+
+# serialization
+*.toml  text

subtype-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: release
+
+on:
+  release:
+    types: [released]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

subtype-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# this project
+extern/

subtype-0.1.0/.gitmodules

@@ -0,0 +1,5 @@
+[submodule "extern/typeshed"]
+	path = extern/typeshed
+	url = https://github.com/python/typeshed
+	ignore = untracked
+	shallow = true

subtype-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+prune extern/typeshed

subtype-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: subtype
+Version: 0.1.0
+Author: crypt0lith
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: typing-extensions>=4.15
+
+Provides a metaclass that extends runtime type checking to the full Python typing spec.
+
+## Usage
+
+### `isinstance`
+
+`subtype.isinstance(obj, T)` answers whether `obj` is assignable to the type expression `T` under the typing spec, and narrows `obj` to `T` for a static checker when it is. Code can then enforce its own annotations on values that only exist at runtime, where a static checker can't see them.
+
+```python
+import subtype
+
+assert subtype.isinstance([[1, 2], [3]], list[list[int]])
+assert not subtype.isinstance([[1, 2], ["3"]], list[list[int]])
+```
+
+Where the builtin `isinstance` raises `TypeError` for a parameterized generic, `subtype.isinstance` checks the items of a collection against its type arguments, including nested collections.
+
+```python
+from collections.abc import Iterator
+
+assert subtype.isinstance(zip(range(3), "abc"), Iterator[tuple[int, str]])
+```
+
+`subtype.isinstance` infers an iterator's item type from the objects the iterator was built from, without advancing it.
+
+```python
+from collections.abc import Callable
+from typing import Protocol
+
+
+class StrCall(Protocol):
+    def __call__(self, o: object, /) -> str:
+        return str(o)
+
+
+assert subtype.isinstance(str, StrCall)
+assert subtype.isinstance(str, Callable[[object], str])
+```
+
+A class matches a `__call__` protocol by its constructor, the same way it matches `Callable[...]`.
+
+### `subtype`
+
+`subtype(T)` turns the type expression `T` into a class that `issubclass` accepts, and answers whether a type is assignable to `T` under the typing spec.
+
+```python
+from collections.abc import Sequence
+
+from subtype import subtype
+
+assert issubclass(list[bool], subtype(Sequence[int]))
+assert not issubclass(list[bool], subtype(list[int]))
+```
+
+`issubclass` takes a type expression as its first argument, and compares type arguments by the variance of their type parameters.
+
+```python
+from typing import Self
+
+assert issubclass(str, subtype(Sequence[Self]))
+```
+
+`subtype` binds `Self` to the class being checked, so `str` is checked against `Sequence[str]`.
+
+```python
+from collections.abc import Callable
+from typing import Protocol, overload
+
+
+class Decode(Protocol):
+    @overload
+    def __call__(self, data: bytes) -> str: ...
+    @overload
+    def __call__(self, data: None) -> None: ...
+
+
+assert issubclass(Decode, subtype(Callable[[bytes], str]))
+```
+
+Protocols are matched by the signatures of their members, not only by member names as with `runtime_checkable`. A protocol's `__call__` is checked against `Callable[...]` like any other callable, overloads included.
+
+## Installation
+
+Install the package via `pip`:
+
+```shell
+pip install subtype
+```

subtype-0.1.0/README.md

@@ -0,0 +1,88 @@
+Provides a metaclass that extends runtime type checking to the full Python typing spec.
+
+## Usage
+
+### `isinstance`
+
+`subtype.isinstance(obj, T)` answers whether `obj` is assignable to the type expression `T` under the typing spec, and narrows `obj` to `T` for a static checker when it is. Code can then enforce its own annotations on values that only exist at runtime, where a static checker can't see them.
+
+```python
+import subtype
+
+assert subtype.isinstance([[1, 2], [3]], list[list[int]])
+assert not subtype.isinstance([[1, 2], ["3"]], list[list[int]])
+```
+
+Where the builtin `isinstance` raises `TypeError` for a parameterized generic, `subtype.isinstance` checks the items of a collection against its type arguments, including nested collections.
+
+```python
+from collections.abc import Iterator
+
+assert subtype.isinstance(zip(range(3), "abc"), Iterator[tuple[int, str]])
+```
+
+`subtype.isinstance` infers an iterator's item type from the objects the iterator was built from, without advancing it.
+
+```python
+from collections.abc import Callable
+from typing import Protocol
+
+
+class StrCall(Protocol):
+    def __call__(self, o: object, /) -> str:
+        return str(o)
+
+
+assert subtype.isinstance(str, StrCall)
+assert subtype.isinstance(str, Callable[[object], str])
+```
+
+A class matches a `__call__` protocol by its constructor, the same way it matches `Callable[...]`.
+
+### `subtype`
+
+`subtype(T)` turns the type expression `T` into a class that `issubclass` accepts, and answers whether a type is assignable to `T` under the typing spec.
+
+```python
+from collections.abc import Sequence
+
+from subtype import subtype
+
+assert issubclass(list[bool], subtype(Sequence[int]))
+assert not issubclass(list[bool], subtype(list[int]))
+```
+
+`issubclass` takes a type expression as its first argument, and compares type arguments by the variance of their type parameters.
+
+```python
+from typing import Self
+
+assert issubclass(str, subtype(Sequence[Self]))
+```
+
+`subtype` binds `Self` to the class being checked, so `str` is checked against `Sequence[str]`.
+
+```python
+from collections.abc import Callable
+from typing import Protocol, overload
+
+
+class Decode(Protocol):
+    @overload
+    def __call__(self, data: bytes) -> str: ...
+    @overload
+    def __call__(self, data: None) -> None: ...
+
+
+assert issubclass(Decode, subtype(Callable[[bytes], str]))
+```
+
+Protocols are matched by the signatures of their members, not only by member names as with `runtime_checkable`. A protocol's `__call__` is checked against `Callable[...]` like any other callable, overloads included.
+
+## Installation
+
+Install the package via `pip`:
+
+```shell
+pip install subtype
+```

subtype-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=80", "setuptools-scm[simple]>=9.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "subtype"
+dynamic = ["version"]
+readme = "README.md"
+authors = [{ name = "crypt0lith" }]
+requires-python = ">=3.14"
+dependencies = [
+    "typing-extensions>=4.15",
+]
+
+[dependency-groups]
+tests = [
+    "pytest>=9.1.1",
+]
+
+[tool.setuptools.packages.find]
+include = ["subtype*"]
+
+[tool.black]
+preview = true
+skip-magic-trailing-comma = true
+target-version = ["py314"]
+extend-exclude = "^/subtype/typeshed/"
+
+[tool.isort]
+profile = "black"
+split_on_trailing_comma = false
+combine_as_imports = true
+skip_gitignore = true

subtype-0.1.0/setup.cfg

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