Update typing for array object dunder methods

[kgryte]

This PR

• updates type hints for various array object dunder methods, as mentioned in gh-143 (comment).
• updates parameter descriptions to match element-wise counterparts (e.g., MUST vs SHOULD, etc).

[rgommers]

Thanks @kgryte. LGTM.

Technically int is a subtype of float so not necessary to include (and there's a mypy guideline saying to not do Union[int, float] when you can simply do float, however for clarity I think it's preferred to do so here anyway.

[asmeurer]

Technically int is a subtype of float so not necessary to include (and there's a mypy guideline saying to not do Union[int, float] when you can simply do float, however for clarity I think it's preferred to do so here anyway.

__pow__ and __divide__ in the spec currently only require floating-point, meaning for the NumPy API, they error on int inputs. Is that actually correct behavior based on the spec? If so, this is a breakage from the mypy typing. Does mypy have a way to specify float but not int?

[rgommers]

__pow__ and __divide__ in the spec currently only require floating-point, meaning for the NumPy API, they error on int inputs.

That does sound right, x**2 should work right? Only negative integers will error. Which is not something easy to express in type annotation (which is fine).

Does mypy have a way to specify float but not int?

Not that I know of.

[asmeurer]

Actually, I didn't notice that the spec says "numeric data type" for __pow__ and __truediv__ but "floating-point data type" for pow and divide. So I presently had them not working for integer inputs, but I should change this. Or the spec should be fixed (it doesn't mention anything about negative integers for __pow__).

[rgommers]

Ah that should be made consistent. And negative integers should be disallowed I believe.