Tracker: Differences with NumPy

[jorenham]

This is a temporary tracker issue for the major differences between the stubs provided by NumType, and those bundled with NumPy. Once the documentation is online, a dedicated page for these will be created, instead.

---

Backwards incompatible fixes

Scalar type methods

• [c]longdouble.item() and .tolist() now correctly returns [c]longdouble instead of builtins.{complex,float} (💥 concrete complex scalar types #391, 💥 concrete floating scalar types #397)
• moved the is_integer and as_integer_ratio definitions from floating to its concrete subtypes (💥 concrete floating scalar types #397)
• moved the __complex__ and __hash__ method definitions from complexfloating to its concrete subtypes (💥 concrete complex scalar types #391)
• moved the __hash__, __index__, and bitcount method definitions from [un]signedinteger to their concrete subtypes (💥 concrete signedinteger scalar types #407, 💥 concrete unsignedinteger scalar types #408)

Concrete scalar types

• int{8,16,32,64} and long have been made into proper signedinteger subtypes (💥 concrete signedinteger scalar types #407)
• uint{8,16,32,64} and ulong have been made into proper unsignedinteger subtypes (💥 concrete unsignedinteger scalar types #408)
• float16, float32, and longdouble have been made into proper floating subtypes (💥 concrete floating scalar types #397)
• complex64 and clongdouble have been made into proper complexfloating subtypes (💥 concrete complex scalar types #391)
• the discouraged long and ulong scalars are no longer equivalent to [u]intp and [u]int64

Extended precision

• removed [u]int128, [u]int256, float80, float256, complex160, complex512 (⚰️ remove non-existent extended-precision scalar types #209)
• float96 and float128 are aliases of longdouble (💥 concrete floating scalar types #397)
• complex192 and complex256 are aliases of clongdouble (💥 concrete complex scalar types #391)

NBitBase

• numpy.typing.NBitBase should not be used anymore - actively discourage or prevent the usage of numpy.typing.NBitBase #395
• removed the undocumented numpy.typing.NBitBase subtypes, such as _8Bit and _NBitDouble

Quality assurance

API consistency

Unlike NumPy, NumType uses stubtest to ensure that the typing stubs match the runtime implementation.

Type-checkers

The stubs in NumType are also checked by mypy, pyright, and basedpyright (in strict mode) to avoid any errors, and ensure compatibility with the major type-checkers.

Testing

NumPy uses a manual type-testing strategy, and its type-tests are a collection of toy examples that should either be rejected, accepted, or inferred to be of specific type using typing.assert_type.
But there is no mechanism that validates whether these type-tests correctly describe what would happen at runtime. The only way to ensure correctness of these tests, is to manually verify them. In NumPy, the type-tests are evaluated using mypy.

NumType also uses most of NumPy's (manual) type-tests, but validates them with both mypy and basedpyright.
But unlike NumPy, NumType also uses test generation in several places. For the scalar binary operators such as int8.__add__, for example, NumType procedurally generates all possible combinations of scalar types and operators, resulting in a 8283 assert_type statements and 2655 expected rejections. This guarantees that the scalar operator method annotations are correct and accurate for all possible (scalar) input types.

New features

Optional dtype type parameter

The generic scalar-type parameter of numpy.dtype has been made optional, with Any as the default. This allows you to write _: np.dtype instead of _: np.dtype[Any].

The numtype package

TBD

Shape-typing

TBD

[jorenham]

closing in favor of https://numpy.org/numtype/contributing/