DOC: Document a few more methods for Categorical Array

[ivirshup]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.Categorical.html#pandas.Categorical

Documentation problem

The only documented methods for the Categorical class are from_codes and __array__. However a bunch of other methods exist and have docstrings written. These include:

• from_codes
• as_ordered
• as_unordered
• set_categories
• rename_categories
• reorder_categories
• add_categories
• remove_categories
• remove_unused_categories
• map

The above are just some of the methods which are specific to categorical. There are then also methods (with doc strings) like: astype, isin, min, max, describe, etc.

Suggested fix for documentation

I think at least some of these should show up in the rendered docs. Maybe all, but that could also lead to crowded docs.

I see it has been suggested in the past that only selected methods are documented, but I'm not sure if a criteria has been established.

• DOC: Missing PandasArray methods in API #24507 (comment)

At a minimum, I would add all the categorical specific methods that I've listed above.

[ivirshup]

@lithomas1, I'm not totally familiar with the triage process, but wanted to check if these changes we something that pandas was interested in making. I assume because you removed the triage label, it is?

[lithomas1]

Sorry - forgot to leave my comment!

It looks like Categorical might be considered for deprecation (in this issue #55550).

(Personally, though, I don't find the reasons in that issue that compelling, compared to the churn it would create).

We should resolve that before we document more of Categorical.

cc @jbrockmendel

[ivirshup]

Thanks for getting back!

What do you think of considering this separately?

• I believe that proposal is just removing Categorical from the top level pandas namespace. As all the other extension are still documented, (example) I don't think that proposal negates the value of documenting it's methods.
• Even if the proposal is broader (hoping not?) the damage caused by adding docs which are then removed seems minimal.

On the other hand, if that conversation takes a while maybe this gets forgotten and the docs don't get improved.

[jbrockmendel]

I haven't seen any support for the idea of deprecating pd.Categorical from the top namespace, no plans to push on the idea myself. I do think it has a bearing on #56874 since it would be necessary if we wanted to make EAs never-intended-to-be-used-directly-by-users

[ivirshup]

I do think it has a bearing on #56874 since it would be necessary if we wanted to make EAs never-intended-to-be-used-directly-by-users

To me, that issue reads more like a discussion about whether to publicly document extension array private methods like _accumulate and _reduce, rather than the classes themselves.