From 0fc5c391782f776a2d355d724c077785e2717cde Mon Sep 17 00:00:00 2001
From: sneakers-the-rat <sneakers-the-rat@protonmail.com>
Date: Fri, 24 May 2024 18:51:54 -0700
Subject: [PATCH] docs for instance checking

---
 docs/design.md |  1 +
 docs/index.md  | 19 +++++++++++++++++++
 docs/todo.md   | 15 +++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/docs/design.md b/docs/design.md
index b06c4af..2a8d6cc 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -17,6 +17,7 @@ relatively low. Its `Dtype[ArrayClass, "{shape_expression}"]` syntax is not well
 suited for modeling arrays intended to be general across implementations, and 
 makes it challenging to adapt to pydantic's schema generation system.
 
+(design_challenges)=
 ## Challenges
 
 The Python type annotation system is weird and not like the rest of Python! 
diff --git a/docs/index.md b/docs/index.md
index 3d9da31..1e6a1f8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -57,6 +57,25 @@ model = MyModel(array=('data.zarr', '/nested/dataset'))
 model = MyModel(array="data.mp4")
 ```
 
+And use the `NDArray` type annotation like a regular type outside
+of pydantic -- eg. to validate an array anywhere, use `isinstance`:
+
+```python
+array_type = NDArray[Shape["1, 2, 3"], int]
+isinstance(np.zeros((1,2,3), dtype=int), array_type)
+# True
+isinstance(zarr.zeros((1,2,3), dtype=int), array_type)
+# True
+isinstance(np.zeros((4,5,6), dtype=int), array_type)
+# False
+isinstance(np.zeros((1,2,3), dtype=float), array_type)
+# False
+```
+
+```{note}
+`NDArray` can't do validation with static type checkers yet, see 
+{ref}`design_challenges` and {ref}`type_checkers`
+```
 
 ## Features:
 - **Types** - Annotations (based on [npytyping](https://github.com/ramonhagenaars/nptyping))
diff --git a/docs/todo.md b/docs/todo.md
index 6d94b8f..9080e29 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -10,6 +10,21 @@ type system and is no longer actively maintained. We will be reimplementing a sy
 that extends its array specification syntax to include things like ranges and extensible
 dtypes with varying precision (and is much less finnicky to deal with).
 
+(type_checkers)=
+## Type Checker Integration
+
+The `.pyi` stubfile generation ({mod}`numpydantic.meta`) works for 
+keeping type checkers from complaining about various array formats
+not literally being `NDArray` objects, but it doesn't do the kind of 
+validation we would want to be able to use `NDArray` objects as full-fledged
+python types, including validation propagation through scopes and 
+IDE type checking for invalid literals.
+
+We want to hook into the type checking process to satisfy these type checkers:
+- mypy - has hooks, can be done with an extension
+- pyright - unclear if has hooks, might nee to monkeypatch
+- pycharm - unlikely this is possible, extensions need to be in Java and installed separately
+
 
 ## Validation