Issue 20994 reports that scipy.spatial.distance.cosine raises ValueError for certain complex input, while WolframAlpha returns a (complex) answer. PR 21001 proposes a way to support complex inputs, but discussions under that PR reveal that a proper definition of cosine distance between complex vectors is not obvious; even the WolframAlpha answer does not seem meaningful. In addition, the pdist/cdist functions only support real inputs.
Therefore, I propose to emit a DeprecationWarning for complex inputs to the distance.cosine function and the closely-related distance.correlation function. I submit PR 21085 accordingly.
This deprecation is not “typical” in the sense that the deprecated functionality is not documented or well-defined. Nevertheless, issuing such a warning gives users an opportunity to review the usage, should they supply complex inputs to these functions and have DeprecationWarning not ignored.
What about the other two dozen distance functions? I don’t touch them for the moment as no issue has been reported on them (yet).