DOC: Typed NumPY API usage

[leycec]

Documentation

The well-documented Typing subsection exhaustively details our typed NumPy API (which is great), complete with concise examples (which is even greater). With one notable exception pertaining to mypy, however, this subsection lacks a substantive discussion of actual usage – how NumPy type hints are actually used, applied, and enforced in real-world practice (which is less than great).

A trailing subsubsection briefly enumerating usage practicalities could prove useful, especially if doing so curtails discussion churn elsewhere (e.g., on Gitter or this issue tracker).

Since NumPy itself and Python interpreters in general silently ignore annotations, NumPy type hints have no force or effect in and of themselves; by design, they reduce to noops in the absence of external third-party support. There only exist two PEP-compliant type checkers explicitly supporting the typed NumPy API. ^{...to my limited knowledge} Usage of NumPy type hints thus presupposes use of one or both of these type checkers.

Drumroll, please. These are...

Static Type Checking

Static type checkers explicitly supporting the typed NumPy API include:

• mypy, of course.

There exist three other well-maintained static type checkers, but it's unclear whether they currently support the typed NumPy API:

• FaceBook's Pyre.
• Google's pytype.
• Microsoft's pyright.

They probably don't (yet), but probably will (eventually). A simple list or table enumerating which of these checkers support NumPy type hints – and as of which checker version – would go a long way to addressing usage. Likewise...

Runtime Type Checking

Runtime type checkers explicitly supporting the typed NumPy API include:

• beartype, surprisingly.

There exist two other well-maintained runtime type checkers that sadly both fail to support the typed NumPy API:

• Pydantic.
• typical.

Again, a simple list or table enumerating which of these checkers support NumPy type hints – and as of which checker version – would simplify everyone's hectic focus on revolutionizing the world with NumPy.

That's All the Data Scientist Wrote

Thanks for all the jaw-dropping volunteerism, NumPy doco evangelists! I remain in awe of your commitment to sound data science in Python, the language of AI. Everyone here deserves all the thunderous applause I have to give. Sadly, these emoji will have to do.

👏 ⚡ 👏

[melissawm]

Thank you so much for putting in the effort of writing such a good issue! Would you be interested in writing/reviewing such a document? (It is on our list of things-to-be-done)

If this interests you feel free to connect - we have a documentation team that can help and we do hold open meetings. Cheers!

[leycec]

Would you be interested in writing/reviewing such a document?

Yup. Absolutely on both accounts. What I lack in sufficient free time I compensate for with unquenchable thirst and awkward enthusiasm.

My initial thoughts were leading to simplicity and terseness – because the perfect is the enemy of the usable and it would be great to have something where currently we have nothing. Would submitting a PR appending or prepending a new draft subsection to the existing typed API expose be a reasonable starting place?

NumPy documentation is vast and sprawling and spreads like a tentacular horror from the Gulf of Mexico across multiple tutorials, manuals, references, quickstarters, API discussions, embedded docstrings, and even more inscrutable sources. As a cretaceous fish out of water, I leave everything up to your discriminating judgement.

Thanks for the prompt reply, Melissa. NumPy devs always the best devs. 😺

[BvB93]

Hi @leycec, if you're interested in contributing you're more than welcome to do so!

While I'm not too familiar with the current state of runtime type checkers, I can provide some insight about static checkers:

Namely, numpy's annotations are based on what was introduced in PEP 484 and the subsequent typing-related peps, standards which static type checkers are expected to (eventually) support. It is definetelly possible that different type checkers might produce (slightly) different results though, be it either due to bugs/features and/or the reality that numpy is pushing the current typing system somewhat to its limits.

An exception to this general rule is, of course, the mypy plugin. As the name implies, this one is exclusively available for mypy.

My initial thoughts were leading to simplicity and terseness – because the perfect is the enemy of the usable and it would be great to have something where currently we have nothing. Would submitting a PR appending or prepending a new draft subsection to the existing typed API expose be a reasonable starting place?

I agree, this sounds like a reasonably place to add more typing documentation.

[leycec]

I agree, this sounds like a reasonably place to add more typing documentation.

Superb. When I find a free moment, ^{...a geek can dream} I'll submit a draft PR and ping you both onto it. Thanks for the rapid and enthusiastic turnaround here, too. Lovin' it! 😄

Namely, numpy's annotations are based on what was introduced in PEP 484 and the subsequent typing-related peps, standards which static type checkers are expected to (eventually) support. It is definetelly possible that different type checkers might produce (slightly) different results though, be it either due to bugs/features and/or the reality that numpy is pushing the current typing system somewhat to its limits.

Yes. Absolutely. I was initially shocked (in a pleasant way) by the depth of the numpy.typing subpackage. It's a dizzying deep dive into the subject of type hinting and a real-world torture test for PEP standards and the official typing module. Bravo!

That said, numpy.typing is a little more nuanced than just PEP 484. Many NumPy type hints are indeed PEP 484-compliant and thus implicitly well-supported across both static and runtime type checkers without any additional work from anyone. That's good. Still other NumPy type hints extend or generalize other PEPs in novel, ingenious, and somewhat non-standard ways that play less nicely with non-mypy type checkers. That's maybe less good... but there was probably no other reasonable way of really doing it. </sigh>

The pivotal numpy.typing.NDArray, for example, extends PEP 585 (specifically, types.GenericAlias under Python ≥ 3.9 and a private NumPy backport under Python < 3.9) in various smart ways that require explicit support. No one gets numpy.typing.NDArray support for free. Static and runtime type checkers (including intelligent IDEs like PyCharm and VSCode + PyLance) that fail to explicitly support numpy.typing.NDArray cry miserably and raise various exceptions, errors, and warnings when confronted with numpy.typing.NDArray type hints in the wild. That's just the nature of the beast – and not necessarily a bad thing. You can't type-check something you never even knew existed, right?

This is why an exhaustive list of static and runtime type checkers that explicitly support numpy.typing out-of-the-box is kinda crucial. While all PEP-compliant type checkers should at least partially support a subset of numpy.typing for free, no type checker fully supports numpy.typing without trying really, really hard to do so.

Thanks again for all the vivacious discussion, everyone. Let's type-check this!

[leycec]

Update: I still have done nothing. </sigh>

That said, I noted this most recent comment on the NumPy gitter:

Hello, using numpy np.ndarray type I get type object is not subscriptable with pylint and it is also raising this error when using runtime type checker like typeguard. I have only found this comment on the repo #7370 (comment). Do you think I should open a bug report ?

...clearly, we have work to do. 😓

[sarimmehdi]

PyCharm still complains loudly when typed NumPy API is used, did anybody find a solution to it?

[leycec]

...ugh. Regretfully, I wasn't able to commit any meaningful resources to this. 2022 is looking equally dense with work, too. I'll happily review anything anyone readies for PR submission, though! This is a non-trivial topic and confusion abounds. Let's set the record straight next year. 😉

@sarimmehdi: PyCharm complaints are orthogonal (although related) to this issue, which is specific to documentation. Would you mind opening up a separate issue for that – assuming there isn't already one?

[ssanya942]

Hey there! I am interested to work on this guide ! Looking forward to contribute!

[ssanya942]

Update

1. The last code in the #APIs section on a typical usage example for NBitBas has no return values. I wanted to inquire if that is supposed to happen because I think that it is supposed to return some numpy.floating/numpy.signedinteger values.

Can someone kindly confirm?

2. The 2nd last code in the #APIs section shall work better if the code snippet
   from typing import Any
   were to be added to it. Increases platform independence and versatility, according to me.

Otherwise, loved how superfluous and diversely functional numpy.typing can be.
I would be delighted if reviewers could let me know if my contributions are worth the while!

[BvB93]

@ssanya942 you’re completely right about point 2, but I don’t quite understand what you’re talking about with point 1; NBitBase is a type, not a function with its own return value. Could you show a concrete example here to illustrate your point?