MNT remove _safe_indexing from api_reference.py - #32728

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

_{Generated for commit: 2fe5bd5. Link to the linter CI: here}

I think we should instead recognise that this is very widely used and make it public. So I'm not very happy about removing it from the API docs.

@adrinjalali You misinterpret my intention.
Either something is public API or it isn‘t. safe_indexing was deprecated in version 0.22 PR #15105. Now it‘s kind of in a limbo: it is private (starts with underscore) but listed under public API. It is the only item there starting with an underscore.

For current users of it, nothing is really changed by this PR.

I am happy to add safe_indexing to the public API if that’s the consensus.

I am going to remove this from the 1.8 milestone. This can always be back-ported to the release branch or added to the the next 1.8 bug-fix release.

If right now, it is officially not public, let's remove it from the public API list.

I wouldn't say that it's not public. To me the fact that it's documented makes it de facto officially public. What makes it unique is that it's the only public function with a leading underscore.

With that in mind, I see two options:

• make it officialy private, by removing it from the doc (this PR). We might want a deprecation to warn users that in the future it may be modified without notice.
• or remove the leading underscore. Requires a deprecation warning for the name change.

I don't have a strong opinion between both options but I agree that the current status is not satisfying.

@jeremiedbb ok to merge?

the fact that it's still documented can be considered a documentation bug.

That's where it's not clear. It's a documentation bug if we consider it private. But it's a naming bug if we consider it public. It doesn't imply the same actions. That's why I think we should clear that question first before taking action.

Historically we've been treated like a public function: it's in the api reference and we make official deprecations for every change.

Alright, then we need to survey how frequently this function is used by other projects, for instance by doing GitHub-wide public code search with some clever filters to ignore public copies of the scikit-learn code base. imbalanced-learn is one example. If there are many other projects/repos (or a few important ones), then we consider making that helper officially public.