[docs] Document linting instructions

[sneakers-the-rat]

Until we get 2.0 done and make the shape annotations uh valid type annotations, we need to document how to make it not blow up your linter.

The rule violation is F22: https://docs.astral.sh/ruff/rules/forward-annotation-syntax-error/ which is a pretty basic one - it's an error that's sort of rare and hard to make, but it's also a rule that is so basic that we shouldn't be violating it (hence 2.0).

Document how to make linters not get annoyed

• [ ] ruff
• [ ] pyright
• [ ] mypy
• [ ] what else?

[blakeNaccarato]

Careful it looks like you made a typo, calling it F22 in your comment here instead of F722 (in case that typo makes its way into the docs via copy/paste).

To help with documenting the pyright case, I've documented some examples copy/pasted from VSCode's Pylance warnings below (pyright reports the same errors but ofc doesn't mention "Pylance"), and a workaround. I've found that it fires a reportInvalidTypeArguments error on the first parameter to numpydantic.NDArray and numpydantic.Shape with the following form:

Expected no type arguments for class "{class}" Pylance(reportInvalidTypeArguments)

where {class} is Shape in the case of numpydantic.Shape. In the case of numpydantic.NDArray it fires overlapping errors for the following {class}es: H5ArrayPath, H5Proxy, Path, VideoCapture, VideoProxy, and ZarrArrayPath.

It also fires overlapping errors on the numpydantic.NDArray annotation itself for the {type}s Tuple[Path | str, str] and ndarray[Unknown, Unknown], reporting errors of the following form:

Type "{type}" is already specialized Pylance(reportInvalidTypeArguments)

The workaround, therefore, is to annotate any individual lines using numpydantic.Shape or numpydantic.NDArray as in the following example (Python < 3.12):

from typing import TypeAlias
from numpydantic import NDArray, Shape

VectorShape: TypeAlias = Shape["*"]  # noqa: F722  # pyright: ignore[reportInvalidTypeArguments]
Vector: TypeAlias = NDArray[VectorShape, int | float]  # pyright: ignore[reportInvalidTypeArguments]

which confines the messy error suppression to these VectorShape and Vector definitions, allowing their use in arbitrary Pydantic models without having to suppress errors there as well.

[sneakers-the-rat]

Super helpful, and needing to do that on every line is absolutely abysmal on my part.

Proper type annotations using Protocol are coming, i just need to find a day or two to make a small PR upstream to pydantic (i think) and then it should be no problem to switch over and then mark the old form for deprecation (i'll give a full major version's warning before removing the string-based syntax).

Thanks for, uh, seeing through the thicket of linter errors for the time being.

[blakeNaccarato]

Glad I could help! If you end up working it into a larger documentation PR to explain some of the other linter behaviors as well, of course feel free to copy/paste/modify any of the language I used above.

Thanks for, uh, seeing through the thicket of linter errors for the time being.

I guess it's a price that I'm willing to pay for using things like numpydantic! There's an alternate universe me who's using older, "stable"/boring tools to do the same work, and I wonder if they're getting things done faster than me, without all the gaslighting by type checkers trying to statically analyze the black magic that numpydantic and company enable.

I've done a bit of work in appeasing the type checker for funky Pydantic tools myself in (the presently poorly documented) https://github.com/softboiler/context_models and elsewhere, so if you need an extra set of eyes on PRs involving convoluted Protocol wrangling, just @ me and I may be able to take a look. I'm a heavy Pylance/pyright user with most/all the warnings turned on so I tend to catch all the ugly errors, for better or worse.

[sneakers-the-rat]

Lovely :):):) I would love a review once I make those changes. And yes a docs pr is due in the meantime