API: Add various deprecated attributes to ._deprecated

[topper-123]

• xref hide Index.get_values in docs and IPython tab completion #28772
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

This add various deprecated attributes to their respective types' _deprecated. The effect is that these are now also hidden when tab-completing, making navigating the pandas attributes easier.

[topper-123]

labels is no longer an atribute on Categorical.

[jreback]

seem fine. Any way to have a systematic test here? I don't necessarly care about the actual tab completion itself (though that would be nice), rather that the list is checked against actual deprecations. An idea: we could parse our doc source for Deprecated and then use that as the source of truth (also could do the same with tests).

[topper-123]

Yeah, I thought about it, but can't think of a method that doesn't parse all the source files, which would be inefficient. Maybe add a deprecated decorator, where instead of manually adding to _deprecations, we'd do:

class AClass:
    @deprecated(hide=True)
    def (self, ...):
        ...

But I'm however not personally particularly interested in implementing this, and it should probably be something that is implemented as an independent project outside of pandas anyway...

[WillAyd]

Could maybe leverage something similar to what I posted in #27353 for AST parsing and check where FutureWarning gets raised, but yea also agree can be done separately

[WillAyd]

Hmm actually it would be nice to have something like that as a test here as well otherwise I can see this getting out of sync very fast

[topper-123]

Yeah, I'd like this to exist, I'm just not interested in coding it up myself :-).

[WillAyd]

I guess I'd prefer not to do something like this without checks and balances (whether a test or a code check of some sort). Especially if exposing to end users via whatsnew it could add technical debt

[jreback]

@topper-123 can you give a manual check in ipython to see if everything is working? I agree an automated test would be nice, but not going to block merging this as its a net improvement.

[topper-123]

I've rechecked, all is ok. I found "reshape" in Series._deprecations, which isn't a method on Series, so I removed it.

The oldest deprecated name I found was NDFrame.ix, which was deprecated in v0.20, so could be removed now.

[topper-123]

I notice I said I was not interested above, which could be seen as a bit negative.

What I meant was that it seems a bit big of a undertaking relative to the benefits IMO, so I don't feel it is worth it to spend time on, relative to other PR...If someone else would like to take it on, I'd be positive to the change.

[WillAyd]

I notice I said I was not interested above, which could be seen as a bit negative.

Ha all good - I understood what you were trying to say. I've flip flopped on the issue so also not a blocker for me, just figured was worth thinking twice about

[topper-123]

Is this ok?

[jorisvandenbossche]

Looks good to me. I agree that a full blown test is not worth to block this.

I was just thinking, an easy test to keep a bit track of this might be to thest that all elements in _deprecations actually exist on the object (so we ensure to remove them when we remove the property/method). Not that things break if we forget to remove a name, but that could ensure we keep this list clean.

[topper-123]

That's a a very small win IMO, because if the attribute doesn't exist, there's not really any loss from the string existing in _deprecations, just a bit untidy. The big wins would be:

• know which deprecated attributed show/should show up in the dir
• know if a not-deprecated attribute is accidentally hidden by its name being added to the _deprecations.

Neither which are trivial to test for IMO.

[jreback]

thanks @topper-123

ok we will have to be vigilant to add things when they are deprecated.