DEP: Formally deprecate np.typeDict

[BvB93]

Closes #17585.

The np.typeDict dictionary is a deprecated alias for np.sctypeDict and has been so for over 14 years (6689502).

This PR formally marks it a such, the module-level __getattr__ now issuing a deprecation warning whenever getting np.typeDict.

[eric-wieser]

My main concern here is that maybe we should be doing the deprecation in the other direction... How many callers of sctypeDict are there? In my opinion, sctypeDict is the worse name, as:

• sc is a weird prefix that we've moved away from
• It mixes lowercase with camelCase into something that is hard to get right.

[BvB93]

My main concern here is that maybe we should be doing the deprecation in the other direction... How many callers of sctypeDict are there? In my opinion, sctypeDict is the worse name, as:

Roughly speaking there about twice as many callers of typeDict compared to its sctypeDict alias.
In the grant scheme of things neither of them seem to be used a lot.

• sc is a weird prefix that we've moved away from
• It mixes lowercase with camelCase into something that is hard to get right.

Switching the deprecation around would fix the first issue; though typeDict very much suffers from the second issue as well.

Personally I don't have any particularly strong opinion about which on to keep and which one to discard.

[eric-wieser]

I suppose the other option is we just deprecate both. np.typeDict(x) is the same as np.dtype(x).type, and set(np.typeDict.values()) is {np.dtype(c).type for c in np.typecodes['All']}

[BvB93]

The only department where sctypeDict is somewhat unique is its keys, as they contain all (?) valid names for fixed-size dtypes.

[mattip]

they contain all (?) valid names for fixed-size dtypes

Do we have a canonical way to get this information without these dictionaries?

[BvB93]

Do we have a canonical way to get this information without these dictionaries?

Not as far as I'm aware, no.
The machinery for constructing all the aliases in sctypeDict is located in numpy/core/_type_aliases.py,
which consists nearly exclusivelly of lots of private functions.

[eric-wieser]

as they contain all (?) valid names for fixed-size dtypes.

Is there a valid reason for a user to actually want this? This is the type of trap that leads to users iterating over these names when they should just be iterating over the types themselves.

[BvB93]

Is there a valid reason for a user to actually want this?

The main reason I can think of is for the purpose of documentation, as the current arrays.scalars docs
fail to mention kind + itemsize based aliases.
Admitetly this is not an argument for keeping sctypeDict, it's one for expanding the documentation.

[eric-wieser]

Right - it's useful internally for generating documentation if we want to go down that route, but any downstream project using it probably is doing the wrong thing.

[rgommers]

In the docs sctypeDict is used 3 times, only once outside of release notes (in this data types section though, which should be authoritative). typeDict is ony used 1 time, in the 1.20.0 release notes.

Right - it's useful internally for generating documentation if we want to go down that route, but any downstream project using it probably is doing the wrong thing.

Agreed. I checked scipy, pandas, scikit-learn, scikit-image, statsmodels and astropy, and there's only two usages in SciPy that look correct but weird.

Given that sctypeDict is the one documented use, I think deprecating typeDict now is right. Deprecating sctypeDict would be useful too, but I'd rather we first clean up the documentation and remove usage in SciPy first, give a heads up to others, and do it in 1.22 or 1.23.

[charris]

@BvB93 needs a rebase.

[BvB93]

Deprecating sctypeDict would be useful too, but I'd rather we first clean up the documentation and remove usage in SciPy first, give a heads up to others, and do it in 1.22 or 1.23.

@rgommers do you feel it would be worthwhile to add a comment in the release note discouraging the use of sctypeDict?

[rgommers]

A release note sounds like a good idea, as context with this PR. I'm not sure many people read it though; adding that note to https://numpy.org/devdocs/reference/arrays.dtypes.html is probably more effective long-term.

[charris]

This looks ready to go. Comments?

[charris]

Thanks Bas.